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1. Introduction 


BE SMART AND READ THIS 

This chapter is written for the first time QNX user who wishes to install QNX on 
an IBM PC, AT, HP Vectra, PS/2 or compatible. The documentation will take you 
step by step through the installation procedure. If you run into problems not 
covered by the manual you may call the QNX technical support line. 

Technical Support 

(613) 591-0941 (9:30 am to 5:30 pm EST) 

The installation involves the execution of a number of QNX utility commands. 
Over time you will become familiar with these commands but right now we will 
only cover the basics needed to get started. Although you can execute the com- 
mands directly, we have provided an install program which will invoke the neces¬ 
sary commands from a user friendly menu. 

It is your choice whether to install the system manually or through the install 
command. Both are documented below (With Install - chapter 2, Manually - 
chapter 3), however the manual method contains much more technical detail. This 
detail is usually appreciated by the technical user and may be overpowering for the 
novice. We recommend that you use the install program and read through the 
manual installation which parallels the execution of the program. In any case, the 
first step is to read the rest of this chapter. 


If you are upgrading DO NOT use the INSTALL 
command. It will destroy your existing QNX files. 

Use the documentation provided with your upgrade. 

1.1 What You Were Shipped 

QNX is provided on several floppy diskettes. Depending on the configuration you 
have ordered, you will have received some (or all) of the following diskettes: 

360K Diskettes 

Disk Directories Contents 

1 QNX 22x Boot 

/cmds Essential commands 

/netboot Operating system images 
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2 QNX 2.2jc loot Utilities 

/cmds 

/eonfig 

/drivers 

/expl 

3 Utilities 1 

/cmds 

4 Utilities 2 

/cmds 

5 "C"-Compiler 1 

/cmds 

/samples 

6 "€ ,? Compiler ?- 

/lib 

/mathlib 

/mathlib8087 


Other commands 
Configuration files 
Disk and graphics drivers 
Explain files 


Utility commands 


Utility commands 


Compiler, Assembler 
and Linker... 

Some C programs 


System library 
Floating point library 
8087 floating point library 


720K/1.2Meg Diskettes 


Disk Directories 

1 QNX 2.2x Boot 

/cmds 

/netboot 

/eonfig 

/drivers 

/expl 

/user/qnx 

2 Utilities 

/cmds 

3 "C” Compiler 

/cmds 

/lib 

/mathlib 

/mathlib8087 

/samples 


Contents 


Commands 

Operating system images 
Configuration files 
Disk and graphics drivers 
Explain files 
User directory 


Utility commands 


Compiler, Assembler 
and Linker... 

System library 
Floating point library 
8087 floating point library 
Some C programs 


QNX 2 


Introduction 



We always ship two versions of QNX. One which runs in real mode on PC’s, 

AT’s and PS/2’s and one which runs in protected mode on AT’s and PS/2’s. There 
is also a special version for old style HP Vectras (earlier than Oct 87). You must 
request the special Vectra version. The standard processor types are: 

PCAT - PC* AT, VECTRA, PS/2 or compatible running in real mode. 

ATP - AT, VECTRA, PS/2 or compatible running in protected mode. 

OR 

HV - Early HP Vectra running in real mode. 

HVP - Early HP Vectra running in protected mode. 

The PCAT and HV boot ran in real mode (like DOS) and limits you to 640K of 
memory. The ATP and HVP boot ran in protected mode and allow up to 15 
Megabytes of memory. 

The same QNX utilities and applications will work on ALL of these versions of 
QNX. Also, any application developed by yourself or others should work equally 
well on each QNX version. The operating system is responsible for providing this 
machine independence. 

1.2 Booting QNX 

To boot QNX, place the disk labeled "QNX 22x Boot" in drive 1 and turn on the 
main power switch of your Personal Computer. If power was already switched on, 
turn it off for at least 10 seconds then turn it back on. 

On a PC, QNX will prompt you for today’s date. You should enter it in the form 
indicated by the prompt. For example, you could set the date and time to 12 Oc¬ 
tober 1987 at 2:34 in die afternoon by typing: 

12 oct 87 2 34 pm 

On an AT or PS/2 the date will be read from the built-in clock/calendar. 

QNX will now prompt you to login with the following message: 

QNX Version 22% Release x node n 

Copyright © QNX Software Systems Ltd. 1982,1993 

Logim 
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You should enter qnx followed by a carriage return at this point 

Login: qnx 

$ 

which will log you in as a super-user. The dollar sign ($) prompt indicates that 
QNX is waiting for a command. You will now have to configure QNX for your 
machine. If you have received a networked version of QNX, you should first 
configure a single machine. After you have gained experience with it, you may 
then configure the other machines in the network. These other machines will boot 
over the network. This is explained in more detail later on. 

You should now go to chapter 2 (install program) or chapter 3 (manual instal¬ 
lation). 
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2. Installation Using The Install Command 

Do not read on until you have read chapter 1. 


If you are upgrading DO NOT use the INSTALL 
command. It will destroy your existing QNX files. 

Use the documentation provided with your upgrade. 

This install program should cover 95% of all installations. The program does not 
perform the installation itself but invokes a set of standard QNX utility commands 
to perform each step. These steps are described in more detail in chapter 3 which 
parallels the execution of the install program. You do not need to read it unless 
you want more detail on what is going on. This way you will learn a bit about 
QNX during the installation. Each utility is described in detail in the Utilities area 
of the manual (Utilities Tab). 

At this point you should have booted QNX and have logged in as described in 
section 1.2. If you have booted from a 360K boot diskette, replace it with the boot 
utilities diskette. Then at the dollar sign prompt type the command 

$ install 

and simply answer the questions presented to you. If you wish to install QNX on 
more than one hard disk partition or on more than one hard disk in the same 
machine you will have to read chapter 3. In this case you may still use the install 
program to create your first QNX partition on your first hard disk. 

If you wish to share you disk with DOS 
we recommend that you install DOS first 
leaving room on the hard disk for QNX. 
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Do not read on until you have read chapter 1. 

This section describes in detail how to install QNX. If you consider yourself to be 
a novice you should probably refer to chapter 2 for a menu-driven installation. 
Even experienced users will like INSTALL. 

The information in this section is useful and worth reading even if you do opt for 
the menu driven install program. Each utility command involved is described in 
greater detail in the Utilities area of the manual (Utilities Tab). 



Controller 


Disk -2 (H2,T2,M2) 


.. cables 


Disk 1 


(Hi / Ti,Ni) 


Bus 

Disk drives are available in various sizes. QNX needs to know the following in¬ 
formation about a drive: 


Number of heads 

Number of tracks on each platter 

Number of sectors on each track 

The total size of the disk will be: 

Total number of blocks is 
Total number of bytes is 


H 

T 

N 


H*T*N 
H*T*N * 512 


Depending on the disk controller, one or more disk drives may be connected to it. 

For QNX to communicate with a hard disk, an interface module called a driver 
must be properly mounted into the operating system. A driver is specific to a par¬ 
ticular disk controller and knows the following information about that controller:. 


■» I/O registers 

- DMA Channels used 

- Interrupt used 
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The MOUNT utility command is used to mount a driver. Each driver assumes a 
default value for the number of tracks, heads and sectors on your disk. For ex¬ 
ample, the XT driver assumes a 10 Meg disk while the AT driver uses the disk type 
defined by your AT setup program to determine the size of the disk. If you have a 
non-standard disk, the values for h, t and n can be overridden when you mount the 
driver. 

The number of heads and tracks should be provided by the vendor when you 
receive your hard disk. Most drives contain 17 sectors per track. If you have an 
RLL drive it may contain 25 sectors per track. If you have an ESDI drive it may 
contain 34 or 35 sectors per track, although some ESDI controllers , for com¬ 
patibility, pretend they have 17 sectors/track but twice the number of heads. 

A driver treats each drive as a consecutive series of physical 512 byte blocks, 
starting at one and continuing to some number which is determined by the capacity 
of the drive (H*T*N). The drivers will normally map blocks through sectors, 
heads and then tracks with increasing block numbers. This minimizes head 
movement. 

Here is a partial syntax of the MOUNT command regarding hard disks. Further 
information on this command can be found in the Utilities manual. 


mount disk drive Idrivers/driverjtame pa =osjype 

h =heads t=tracks n-sectors! track 

NOTE: IF YOU MUST SPECIFY H, T or N YOU MUST SPECIFY ALL 
THREE PARAMETERS 

In this command you have indicated 4 separate pieces of information. - 

drive - The number of the drive from QNX’s point 

of view. QNX allows drive numbers from 
1 to 8. Note that unlike DOS which uses 
letters for drives, QNX uses numbers. Although 
you may choose your own drive numbers, we 
recommend you adopt the following scheme: 

Disk Use 
1. Floppy 1 
2 ' Floppy 2 if present 

continued... 
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3 Hard disk QNX partition #1 

4 Hard disk partition #2 

5 Ramdisk 

6 

7 

8 


driver_name - This identifies the software driver for a 

particular controller, (xt, at,...). 

h, t and n - The physical structure of the hard disk. If 
these parameters are omitted, the driver will 
■ assume a default which may or may not be 
correct. Please refer to the documentation 
on each driver. 

osjype - The name of the partition to use. This may be 

the name qnx, qny, qnz, dos, or a number. 


Type Description 

qnx QNX partition (same as number 7) 

qny QNX partition (same as number 8) 

qnz QNX partition (same as number 9) 

dos DOS 2.1 partition (same as number 1) 

1 ... 255 An explicit operating system osjype 


When MOUNTING it is not necessary to specify the three key parameters of H, T 
and N unless the driver is unable to determine them. The capabilities of each 
driver we supply are described below. 

3.1.1 XT Hard Disk Driver 

A large number of drives now on the market boast an XT compatible hard disk 
controller. This controller must be compatible at the physical hardware level. 
Compatibility at the BIOS (ROM) level is not enough to use this driver. This 
driver assumes the old 10 Meg disk shipped by IBM on their old XT. If you have a 
20 meg disk or one which is not identical to the default you must specify the 
proper number of tracks, heads and sectors. 
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<--Default 


Heads Tracks Sectors SIZE 

XT 4 306 17 10M 

mount disk 3 /drivers/disk a xt 

Other 2 612 17 10M 

mount disk 3 /drivers/disk,xt t=612 h=2 n=17 

Other 4 612 17 20M 

mount disk 3 /drivers/disk.xt t=612 h=4 n=17 


3.1.2 AT Hard Disk Driver 

The AT driver uses the disk parameter table setup by the BIOS to determine the 
size of the disk. ■ This means that you should NOT have to specify H, T or N when 
mounting the AT driver UNLESS you are using a drive other than that shipped by 
the AT manufacturer AND which does not correspond to any of the manufacturers’ 
disk types as defined by the AT SETUP program. 

You would mount the AT driver as follows. The second example is for a drive 
which the does not have a supported disk type in the AT setup program provided 
with your machine. If you are using an unsupported drive, you must specify the 
number of tracks, heads and sectors. 

mount disk 3 /drivers/disk a at 

or 

mount disk 3 /drivers/disk.at t -tracks beheads n -sectors 


3.1.3 PS2 Hard Disk Drivers 

The PS/2 driver(s) use the disk parameter table setup by the BIOS to determine the 
size of the disk. This means that you should NOT have to specify H, T or N when 
mounting the PS/2 driver. 

The model 25 and 30 use the driver in the system BIOS. 

Model 25 9 30 

mount disk 3 /drivers/diskJbios 

There are two controllers available for the PS/2 models 50 and up. One interfaces 
to an ST506 type drive and one to an ESDI drive. The ESDI controller is not cur¬ 
rently available for the model 50. These are high performance drivers which fea¬ 
ture read-ahead and write-behind. You should read the technical note "Page 
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Caching Disk Drivers" in the technical notes section. 

Mode! 50 and tip 

ST506 Drive 

mount disk 3 /drivers/disk.ps2 read technical note 

ESDI Drive (disks > 70 Megabyte) 

mount disk 3 /drivers/disk.ps2esdi read technical note 

3.1.4 HP NIGHTHAWK Hard Disk Driver 

When you purchase an HP vectra there is an optional hard disk and controller 
available for it. It is usually sold into process control markets and at this printing it 
had a part number of 45816A. Within HP, it is sometimes referred to as die 
"Nighthawk" hard disk controller. 

You would mount the driver as follows. 

mount disk 3 /drivers/disk.nighthawk 


3.1.5 BIOS Hard Disk Driver 

This driver uses the INT13 BIOS calls to perform hard disk I/O and will only 
work in REAL MODE versions of QNX. It will work on any controller card or 
machine which supports INTI3 hard disk I/O. These cards usually contain a ROM 
which the BIOS finds and executes when power is turned on. This allows us to 
provide immediate support for the many new drives on the market. The BIOS 
driver reads the disk configuration table set up by the BIOS to determine the 
physical characteristics of the hard disk. This can be over-ridden (if required) by 
specifying tracks, heads and sectors on the mount command. This driver should 
only be used as a last resort. 

This is a busy-wait driver and may cause a slight stutter effect in a multi-user en¬ 
vironment. The BIOS driver will not work in protected versions of QNX (ATP) 
nor can it be used with the DOS emulator. 

mount disk 3 /drivers/diskJbios 
or 

mount disk 3 /drivers/diskJbios t-tracks h-heads n=sectors 
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3.2 Step-by-step Installation of Hard Disk 

At this point you should have booted QNX and have logged in as described in 
section 1.2. The procedure required to install QNX onto your hard disk is de¬ 
scribed here in a step-by-step fashion. 

NOTE that any QNX command will print a short usage message when a ’?’ is 
specified as the only command line argument. If you wish to know more about the 
commands, please refer to the "Utilities" manual. 




111 Creating a QNX hard disk partition 


To create a hard disk partition on your disk, you must use the commands outlined 
below with the proper arguments. 

f..’.:.~~~~ Step la - Mounting a Hard Disk Driver _ . 


QNX supplies a number of drivers for hard disks under the directory ’/drivers’ on 
your boot diskette. The following drivers are provided: 

File Name Description 

/drivers/disk.xt XT hard disk driver 

/drivers/disk.at AT hard disk driver 

/drivers/disk.bios BIOS hard disk driver 

/drivers/disk.eighthawk Hewlett-Packard nighthawk hard disk driver 

A standard HP Vectra uses the AT driver 
/drivers/disk.ps2 PS2 ST506 hard disk driver 

/drivers/disk.ps2esdi PS2 ESDI hard disk driver 

Once you have decided on the appropriate driver file, you must mount it into the 
system using the MOUNT command. Until the driver is mounted you will be 
unable to access your hard disk. 


At this point you should mount the hard disk as one large volume. Once the 
driver is loaded you will be able to read and write to block 1 of the disk which 
contains the partition information. You will then use FDISK to set up a QNX 
partition and immediately remount the driver specifying that it constrain itself to 
block accesses within the created partition. Some examples follow: 
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XT with standard Id Meg disk (default) 
mount disk 3 /drivers/disk.xt 

XT with 2d Meg Seagate ST255 disk 

mount disk 3 /drivers/disk.xt h=4 n=17 t=612 

AT with standard 2d Meg disk (disk type 2) 
mount disk 3 /drivers/disk.at 

AT with nonstandard 6d Meg disk (disk type unknown) 
mount disk 3 /drivers/disk.at h=7 n=17 t=98d 

In the last example the user has installed a disk drive which does not match any of 
the defined disk types known by the AT SETUP command. 

I ; . ' Step 1b .- Partitioning' Your Hard .Disk. 


You will now have to partition all or part of your hard disk for the exclusive use of 
QNX. Partitioning allows different operating systems to share a single hard disk 
without conflicting with each other. 

You should now run the FDISK command to set up a QNX partition on the newly 
mounted disk. 

fdisk 3 

Look at the bottom of your screen and verify that the size of your disk and the 
values for H=, T= and N= are reasonable. If they do not reflect what you believe 
to be the size of your disk, then either the disk type is incorrect (AT, PS/2), the 
default values are incorrect (XT) or the wrong values for h, t and n were provided 
to the MOUNT command. 

There are 4 partition slots. Use the up/down cursor keys to select one that is not in 
use. Type the letter c to select the change option. You should now enter the OS 
type (7 for QNX) and the start and end,cylinder to be used for the QNX partition. 
Enter a carriage return after entering each number. The QNX partition may be any 
size up to 1 terabyte which easily covers all disks on the market today. 

If other partitions already exist, your QNX partition must NOT overlap them. If 
the DOS partition takes up the entire drive you will have to reboot DOS, backup all 
your DOS files and reduce the size of the DOS partition before creating a QNX 
partition. If there is room for a QNX partition, then after you have made your 
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changes you must type s to save them back to the disk. Then type q to quit. Hie 
following is a typically partitioned hard disk as seen in FDISK. 


Ignore Next Prev Change Delete Mount Boot Unboot Save Quit 

OS start End Number Boot 

Cylinder Cylinder Cylinders Blocks 

1. dos { 1 ) 1 350 350 23867 

—> 2. qnx ( 1 ) 351 612 262 17816 * 


Use up/down arrows to select partition. 

Type the letter ,c to change/add a partition. 

Type the letter s to save your changes. 

Type ■the letter q to quit. 

QNX is os type 7,8 or 9 DOS is os type 1 or 4 Unused is os type 0 


First cylinder is 0 Last cylinder is 614 
Disk is 21,411,840 bytes T=615 H=4 N=17 


Step 1c - Remount Disk to use the QNX Partition 


Now that you have created a QNX partition you MUST re-issue the mount for 
drive 3, to restrict it to the new partition. This time we will not specify a driver, but 
use the d -driver jium option to tell mount to use the same driver as it is currently 
using for drive 3. For example: 

mount disk 3 d=3 pa=qnx 

mount disk 3 d=3 t=612 h=4 n=17 pa=qex 


You now have a fully functional disk driver mounted and can set up a QNX file 
structure. 
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This MOUNT with the d =drive_num and the previous MOUNT and FDISK com¬ 
mands need only be done this one time to set things up. From now on, each time 
you boot QNX you will have to mount the disk driver with the pa=qnx option and 
if necessary the h=, t= and n= options. For example: 

mount disk 3 /drivers/disk.at pa=qnx 

mount disk 3 /drivers/disk.xt t=612 h=4 n=17 pa=qnx 

You will be shown a little later how to place this mount command in a system 
initialization file which is automatically executed each time you boot. 


Step Id - Format QNX partition (AT’s only) 


Unless you have mounted /drivers/disk.at you should skip this step. 

Users installing QNX on an AT may gain a significant performance increase by 
reformatting the QNX partition with a different interleave than that used by DOS. 
This step is optional but highly recommended. Use the FDFORMAT utility with 
the +hard option to reformat the QNX partition. 

fdformat 3 +hard - Format partition for drive 3 with 
the default interleave (s=6). 

If you have a very fast machine (16 MHz 386) then you may wish to format with a 

smaller interleave (also called stagger). 

fdformat 3 +hard s=5 - Format partition for drive 3 with 

an interleave of 5. 


If you attempt to format a non-AT hard disk you will receive errors and the disk 
should not be affected. 
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Initializing the QNX File Structure 


To Initialize the file structure for your disk, you must use the commands outlined 
below with the proper arguments. 


Step 2a - Create a QNX File System 


Before you can use your QNX partition you must create an empty QNX file system 
on it. This is done with the DINIT command. The command takes the drive 
number of the disk and a flag to indicate that it is a hard disk. Type the following 
command: 

dinit 3 +hard 

The DINIT command is also used to initialize the file system on floppy diskettes 

__ j *11 ^ ^ 14 ^ nnu 0 . 

dliil JL uu will UiClWlWiC UL&v tlllo WMAlMiiciliHj. lilciiiy tliliCo. 1 liC 41 

option is necessary only when initializing a hard disk and protects you should you 
accidentally type in the wrong drive number when initializing a floppy. 


Step 2b - Mark Tracks You know are Bad 


If your hard disk was shipped with a sheet of paper containing a list of bad tracks 
then you may use the DMARK command to explicitly mark the blocks on these 
tracks as un-usable. If you are willing to trust the DCHECK command to find all 
bad blocks you may skip this step. (On occasion, where blocks are intermittently 
bad, DCHECK may miss them). The DMARK command takes a list of tracks and 
heads. Each pair is separated by a space and the track and head are separated by a 
comma. For example: 

dmark 40,4 250,2 500,0 >3:/badJblks - mark track 40 head 4 

250 2 

500 0 


We have redirected its output to 3:/bad blks so that it can be used with the 

DCHECK utility. 

Note that even if only a single block is bad, the entire track is sacrificed. This is 
because interleaving of sectors on the disk locates blocks in different places, 
beyond our control. 
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You should now check for bad blocks in your QNX partition. The DCHECK 
command will attempt to read every block and will report any bad blocks it 
discovers. We will invoke it with the +mark option which will set these blocks as 
un-usable in the hard disk’s allocation bitmap. 

DCHECK will also look for /badblks file on the specified drive. If there is one, 
any block numbers it contains will be marked as un-usable in the bitmap. Any bad 
blocks it has found during its reading of the disk are added to the /bad blks file. 
Type the following command: 

dcheck 3 +mark 

This command may take a while on large disks. 



Copy Files from Floppies to Hard Disk 


To transfer the files from the floppies you have received to your hard disk, you 
must use the commands outlined below with the proper arguments. 


Step 3a - Copy Files From Boot Flo 


You are now ready to copy the QNX files from your floppy diskettes to your hard 
disk. This is done with the BACKUP utility command which copies files and 
directories from one location to another. It takes as arguments, the source direc¬ 
tory and the destination directory, followed by options. Place the disk labeled 
QNX Boot in drive 1 and type the following command: 

backup 1:/ 3:/ +all s=c 

I L Suppress clearing the modify bit. 

L Copy all files. 

L Destination is root directory on hard disk. 

L Source is root directory on floppy diskette. 


Step 3b - Take Commands From Hard Disk 
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You now have enough commands on the hard disk to switch over to it. This is 
done with the SEARCH command which tells QNX which drives to search when 
looking for commands. Currently your search order is 1 (single floppy) or 1 2 (two 
floppies). Type the following command: 

search 3 


Step 3c - Copy Other Floppies to Hard Disk 


You should now copy the files on your other floppy diskettes to the hard disk. 

Type the following command for each floppy diskette you received. 

backup lit 3:1 +all s=c - utilities diskette 

backup til 3:1 +all s=c - c compiler diskette 

... etc* 

The backup command is the easiest way to move the files on any diskette you 
receive from QNX Software Systems Ltd. to your hard disk. Pressing the up-arrow 
key recalls the last line and allows you to easily issue multiple BACKUP com¬ 
mands. 



Makinq QNX Boot From Hard Disk 


The following describe the steps you will need to take to get a QNX hard disk 
partition to boot from hard disk. 


Step 4a - Set OS imaae file to boot 


You will need to use the BOOT command to enable hard disk booting. Its syntax 
is of the form: 

boot os_file_name lc=config_Jile] [d=disk_driver] [-pause] [+qnxloader] 
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osJilejname 

If you have properly backed up the floppies, you now have at least two OS 
image files (osjilejiame) under the /netboot directory on your disk. One is 
os.2.10pcat (REAL MODE), the other is os.2.10atp (PROTECTED MODE). 
If you have the special HP Vectra version, they will be os.2.10hv and 
os.2.10hvp. One of these needs to be specified as the first argument to the 
BOOT command. This mechanism allows you to easily change whether you 
want to boot real or protected mode. It is also handy if you download a beta 
version of an OS from QUICS, our online update system, and wish to try it 
out. 

[c=conflg_file] and [-pause] 

These are not described here. See the section called "Changing Operating 
System Defaults", as well as the "Utilities" manual for more details. 

[d=disk_driver] 

When QNX boots, it needs a hard disk driver in order to access the hard disk. 
Unlike DOS, it cannot use the BIOS driver which does not work in protected 
mode. You must specify which hard disk driver to bind into a hard disk boot. 
The d^diskjdriver option creates a file called /config/hdisk.cfg which is 
loaded in from hard disk along with the operating system file osjilejiame. 

[+qnx!oader] 

To boot QNX you must create a hard disk boot loader. You have two choices. 
You can use the default loader used by DOS or you can use a special QNX 
loader. The former will always boot the active partition as set by the QNX or 
DOS FDISK program. The latter will default to the active partition ( which 
can be DOS ) but will pause for several seconds and allow you to override it 
with another partition number which you may specify by typing in a single 
digit from 1 to 4. This gives more flexibility. However, if you have non¬ 
standard hardware or are already using a special loader then the QNX loader 
may cause you problems. For 99.9% of all installations we recommend you 
use the QNX loader. 

IF YOU DO NOT HAVE A BOOTABLE DOS PARTITION 
YOU SHOULD SPECIFY THE QNX LOADER 

You need only specify the d=disk__driver and +qnxloader options the first time 
you configure for hard disk booting. Later, if you wish to boot a different operating 
system (OS), simply specify the osjilejiame argument to the BOOT command 
and nothing else. Here are some examples: 

1) Boot real mode on an XT, using the DOS loader, 
boot /netboot/os.2.10pcat d=/drivers/disk.xt 
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2) Boot protected mode on an AT, using the QNX loader. 

boot /netboot/os.2.10atp d=/drivers/disk.at +qnxloader 

3) Specify a different OS to boot, leave the driver and loader intact. 

boot /netboot/testos 

NOTE*. Regarding the /netboot/os Jllejname and /config/hdisk.cfg files, you 
may copy a new file on top of them but NEVER remove them (FREE, RM,...) and 
then create a new one even if they have the same name. The BOOT command 
saves away the absolute start blocks of each of these files which will change once 
the file is removed. The BOOT command will always reset the proper starting 
block. 


Step 4b - Make partition bootable 


Your last step is to make the QNX partition the active, bootable partition. Type in 
the FDISK 3 command again, use the arrow keys to point to the QNX partition and 
type the letter ! b’ for boot,(this will put a under the "boot" heading ), the letter 

Y for save and finally the letter ’q’ to quit. 


fdisk 3 

Select QNX with upldown arrows 
Type the letter b 
Type the letter s 
Type the letter q 


Make bootable. 
Save. 

Quit. 


You should now be able to boot from hard disk. Open the door to your floppy and 
simultaneously press the following 4 keys: 


CTRL ALT SHIFT DEL 


3.3 Creating A System Initialization File 

Each time QNX is booted it will execute the commands in a file called 

/config/sys.init.iwwn - Specific to node nnnn, initial choice. 

or 

/config/sys.init - Default. 

where nnnn is the node number of the node which is booting (if you do not have a 
networking card, QNX will look for "sys.init.O" ). If that file does not exist then it 
will try /config/sys.init (no node postfix). 
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config 

i-1- 1 — - 1 -:- 1 

sys.init sys .init. 0 sys .init. 1 sys .init. 3 

default 


The message which greets you each time you log in is currently in the sys.init file. 
As you become acquainted with QNX, you will probably wish to add commands to 
this file which will customize QNX to your needs. This file typically contains 
commands to mount special disk drivers, set terminal options and perhaps read the 
date from a clock/calendar card. We will quickly illustrate a typical system 
initialization file. These files can be created, and may be modified with the editor 
(ED). You may want to refer to the section called ’’Tips on Using QNX' 1 . 

rtc at Set QNX’s date. ( AT*s only ) 

mount bmcache d=3 Mount a bitmap cache 

mount cache d=3 s=32k Mount a directory cache 

mount xcache s=4k Mount an extent header cache 

mount float Mount a floating point library 

mount lib /drivers/glib.ega Mount graphics and 43 line console 

library 

mount console $con2 Mount a second virtual console 

cp /expl/logo $con Print QNX logo 

clock a=fl04 & Put a clock in top right corner 
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3.4 Summary 

The following chart summarizes the steps necessary to install QNX on an AT hard 
disk. 

i 

| Mount the driver as disk 3 

I 

mount disk 3 /drivers/disk.at 
Create a QNX partition 

fiisk 3 

Re-mount the QNX partition 

mount disk 3 d=3 pa=qnx 

Format QNX partition (AT’s only) 
fdformat 3 +hard 
Initialize the hard disk 
dinit 3 +hard 

i 

| Check and mark bad blocks 

I 

dmark 3 track Jiead >3:/badJbIks 
dcheck 3 +mark 

Backup the contents of your BOOT floppy 
backup hi 3:/ +all s=c BOOT disk in drive 1 
Change your search order 
search 3 

I 

| Backup the remaining diskettes 

I 

backup hi 3:1 -4-all s=c Repeat for each floppy 

\ 

| Set OS image file to boot and hard disk driver to use 
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boot 3:lmtbootlosname d=/driver s/disk.at 


| Make ONX partition bootable 

I 

fdisk 3 


3.5 Creating A Login Password File 

QNX has the capability of supporting more than one user at a time, many of which 
may be located at remotely attached terminals. For this reason you may wish to 
restrict access to the system and its files by creating a file of allowable userids and 
passwords. This capability is activated by the command 

"passon" 

NOTE: Passwords are automatically turned on when a machine is booted from 
the network. This means you will have to create a password file if you are booting 
from the network. 

After prompting for the login and password 

Login: John 
Password: 

QNX attempts to open the file "/config/pass". If it does not exist then access will 
be denied. 

Users are identified by a userid and a group and member number which determines 
their permissions. QNX supports up to 256 groups each with a maximum of 256 
user numbers ranging from 0 to 255. Group number 255 is privileged. For ex¬ 
ample, user number 0.21 has unrestricted access to all his own files but may only 
access the files of other users according to the permission fields of the file. This 
field is displayed by the FILES command when invoked with the +verbose option. 

files +v 

The default permission assigned to a file when it is created is "read". This allows 
other users to read it, but they may not write to it, append to it or delete it. If de¬ 
sired, you may remove the read permission by using the CHATTR command as 
follows. 

chattr filename p=~r 
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The file "/config/pass" is created and updated using the editor (ED). This file 
should be created by the super-user (member of group 255) and should have read 
permission removed from it. It consists of a five line entry for each userid. All 
lines except the USERID line should be indented by ONE tab. 

USERID 

** PASSWORD 

tab USER NUMBER (Group.Member) 

** LOGIN DIRECTORY 

*4 LOGIN COMMAND 


The USERID is the character string which must be entered in response to the 
"Login:" prompt. It may contain any characters including blanks and control 
characters. 

The PASSWORD is the character string which must be entered in response to the 
"Password:" prompt. If this field is left blank, then this userid does not have a 
password and may be logged in without one. The password may also contain any 
characters including blanks and control characters. NOTE: the leading tab is still 
needed even if the password itself is absent. 

The USER NUMBER is a pair of numbers between 0 and 255. The first number is 
the group, the second is the member of that group. These numbers identify the user 
to the system and determines his/her file access capabilities. Each userid will 
typically be assigned a unique user number. However, you may assign more than 
one userid the same user number if you wish them to have the same file 
capabilities. 

The LOGIN DIRECTORY is the name of the directory to place the user at, after 
successfully logging in. 

Finally, the LOGIN COMMAND is any QNX command which will be executed 
upon logging in. In a student environment this should be kept consistent for all 
students. Executing a user profile like "ec user.init" is a good choice. 

Typical user.init 

fortune 

ap waiting list alarm 
umail waiting 
path !/cmds/!/cmdsl/H 
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An exclamation mark (!) at the beginning of the LOGIN command will transfer 

directly to that command. This allows custom applications to be called directly 
when the user logs in without allowing them to return to a shell when the program 
terminates. 

The following example illustrates a simple four user file. 

superman 
tab dark kent 

tab 25S.25S 

tab /user/superman 

tab IS 

jasmith 

tab qwerty 

tab Ool 

tab /user/jasmith 

tab ec userinlt 

jqpublic 

tab 

tab 0.2 

tab /user/jqpublic 

tab 

dbase 

tab abc 

tab 1.0 

tab /dbase/data 

tab dbase 


superman has been assigned group number 255 and can do anything. Userid 
jqpublic has no password, and may be logged into by anyone. It also has no initial 
command to execute. 

In an environment where there are many users it is convenient to assign userids 

based upon first and second initial followed by the last name. Mr. Jim A. Smith 

would be jasmith as in the example above. 

The password file must be accessible to all users when they login. In a network, it 

is usually placed on the boot server node. Keep in mind that once this file exists 
then you must live by its login rules. Should you corrupt it you may not be able to 

log into the system. It should be pointed out that this security system is only effec¬ 
tive once QNX has been booted, the disk containing the password file mounted, 
and the PASSON command executed (unless you booted from network). For this 

reason, access to the system unit should be restricted. 
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By convention, QNX places user directories under the directory "/user". There will 
typically be one directory for each user. The directory "/user" should be owned by 
the super user and only he may create new user directories directly under it. Each 
sub-directory under "/user” should be owned by the user assigned to it. The fol¬ 
lowing procedure for adding a new user may be followed. In the example we will 
add a new user with name "jasmith" and user number 0.12. 

1. Login to the super user. 

2. Create the new user directory under "/user". 

mkdir /user/jasmith 

3. Assign the new user a number and give him ownership. 

chattr /user/jasmith g=0 m=12 

4. Read the file "/config/pass" into the editor and add 
a password entry for the new user. 

jasmith 
mb xyz 

tab 0.12 

tab /user/jasmith 
tab ec user.init 

5. Write the file back and you should have successfully 
added a new user to the system. 

3.6 Mounting a DOS or Second QNX Partition 

You can mount more than one hard disk partition at a time. When you mount the 
second or third partitions you replace the name of the driver with a d-drive op¬ 
tion. The drive is the drive number of an already mounted partition. The partition 
to mount is selected using the pa -osjype option. For example, the following will 
mount two QNX partitions and one DOS partition on an AT. 

mount disk 3 /drivers/disk.at pa=qnx 

mount disk 4 d=3 pa=qny 
mount disk 6 d=3 pa=dos 

The DOS partition can only be accessed by the DOS emulator or DFS package. 
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We have reserved the osjype numbers 7, 8 and 9 for QNX. When you mount a 
disk .you may either specify its number or one of the following symbolic names. 


pa-qex same as 
pa=qey same as 

pa=qnz same as 
pa=dos same as 


pa=7 

pa=g 

pa=9 

pa=l or pa=4 


Most of the hard disk controllers can support more than 1 physical hard disk. To 
mount a second disk use the d= and p= option on the mount command. For ex¬ 
ample, assume that an AT controller has two 20 Meg disks attached to it, and both 
have QNX partitions on them. 

mount disk 3 /drivers/disk.at pa=qnx - disk 1 
mount disk 4 d=3 p=2 pa=qnx - disk 2 

The p= option specifies which physical_drive to use. The default is to use physical 
drive 1, which is why it was not required in the initial installation. 

3.8 Changing Operating System Defaults 

The BOOT command allows you to specify a configuration file ([c=config_file]) 
which lets you change some of the operating system defaults such as the number of 
open files supported. 

A configjile is created and maintained by the OSCONFIG command. It is de¬ 
scribed in detail in the "Utilities’' manual. It takes a file name as an argument. For 
example: 

osconfig 3:/config/sys.cfg 

would create a configuration file for a single non-networked machine. It does not 
become active until you use the BOOT command to set it. For example: 

boot 3:/netboot/os.2 o 10pcat c=3:/confIg/sy s.efg 

You may select any file name, however, when booting over the network QNX will 
automatically look for /config/sys.cfg.R« with nn replaced by your node number. 
For this reason we recommend you adopt this convention, even on a single 
machine, although on a single machine you may omit the ".nn" extension. 
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/config/sys.cfg - Single machine. 

/config/sys.cfg./in - Network machine. 

NOTE: When booting from hard disk you should not remove the os filename, 
the driver filename or the config file name. 

Inetbootlosname 

/config/hdisk.cfg 

/config/sys.cfg 

You may copy a new file on top of them but NEVER remove them (FREE, RM, 
...) and then create a new one even if they have the same name. The BOOT com¬ 
mand saves away the absolute start blocks of each of these files which will change 

once the file is removed. 

3.9 Removing the QNX loader 


The bootstrap loader created by die [+qnxloader] option of the BOOT command is 
compatible with that created by the DOS FDISK utility when a hard disk is par¬ 
titioned for the first time. However, some compatible PC’s or AT’s may have a 
different bootstrap loader placed in block 1 of the disk. 

If you have used the [+qnxloader] option with the BOOT command, and now find 
that DOS no longer boots and you wish it to, you can use the QNX FDISK com¬ 
mand to remove the special signature (55AA) from the boot block. This will en¬ 
able the FDISK command under DOS or QNX to re-write a new loader. For exam¬ 
ple: 


fdisk 3 +r 

The ^remove option to FDISK should rarely be used and is not documented 
elsewhere. 
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4. Network Installation 

Do not attempt network installation until you have read chapter 1 

and 

completed the single machine installation in chapter 2 or 3. 

Now that you are successfully running QNX on one machine you can start to con¬ 
nect several machines in a local area network. You will need a local area network 
card for each machine in the network and a version of QNX configured for the 
proper number of computers (nodes ). 

4.1 Hardware Installation 


Please refer to the documentation which was provided with 
the networking card. It should have been supplied as an 
insert to be added to the standard manual. 


4.2 Software Installation 

Your first machine (the boot server) must boot from disk. Each other machine in 
the network may optionally boot from disk or over the network, from the disk of a 
boot server. It is possible to configure work stations without any disks whatso¬ 
ever, using only remote disk storage. 

If you have three or more networking cards we recommend that you first attempt to 
connect only two machines together. 

In the following sections you will want to place the indicated commands in the 
system initialization file of the boot server. More information on the commands 
may be found in the "Utilities” manual. 




onfigure 


Size 


When booted from floppy disk, QNX will not communicate on the network. The 
netsize utility must first be executed to configure the size of your network. This 
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utility will prompt you to insert your boot disk, and any network expansion disks 

which you have purchased. A total network size will be calculated and recorded 
onto the hard disk. A directory of files will also be maintained on the hard disk (in 
the /netdisks directory) for informational purposes. To use netsize, you simply 

type: 

$ netsize 

and insert boot or network expansion disks when prompted. 

For details about unusual network configurations, please refer to the documenta¬ 
tion on NETSIZE in the utilities section of this manual. 




w 


Selecting Node Numbers 


From QNX’s point of view, each card must have a unique network address. QNX 
node id’s may lie between 1 and 255. You should configure your node id’s to start 
at 1 and attempt to setup the node id’s to be consecutive. Most users select node 1 
to be their main machine (boot server). 


max machines 


[Hi Setting a Remote Search Order 


When a machine boots over the network it will have its search order set to the 
machine it booted from. It will also inherit the date. Since all commands and files 
are coming from the boot machine you must define a remote search order for the 
boot server using the SEARCH command. 


search 3 4-remote 

You should place the remote search command in the system initialization file for 
the boot server (eg. /config/sys.init.l ). 
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If you wish non-super-users to use the hard disk you must use the NACC com¬ 
mand to allow network access. This command takes a list of drive numbers and 
device names to allow/disallow. To allow read/write on disk 3 enter the command. 

nacc 3 +read + write 

Since the search order of a node which is booting over the network will be to the 
boot server, you should place the network access command in the system initializa¬ 
tion file for the boot server. Otherwise machines will hang when they boot 
because they can’t find an appropriate sys.init.iin file in their search order. 


m 




■8W® 




Creating System Initialization Files 


As each machine in the network boots it will attempt to execute the file 
/config/sys.imt.f!H where nn is the node number of the machine. If that file does 
not exist then it will try /config/sys.init (no node postfix). 

config 

i- 1 - 1 — 1 -r--- 1 

sys. init sys.init.1■ sys. init .2 sys. init. 3 
default 


We recommend that sys init be a relatively harmless set of generic commands 
similar to the one shipped on your boot diskette. This allows you to quickly boot a 
new machine on the network. Once that machine is booting successfully you can 
then create a custom sys.init.nii for it. 

See the description on "Creating a System Initialization File" in chapter 3. 


Create a Password File 


Since any machine which has booted over the network from a boot server always 
has passwords enabled, it is necessary that a password file /config/pass exists 
somewhere in the search order. 
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See the description on "Creating a Password File" in chapter 3. 



Starting the Netboot Task 


Before a machine (boot server) can boot other machines, you must run a back¬ 
ground task which accepts boot requests from the network and downloads the 
contents of operating system image files (< osjilejiames ) to the requesting 
machines. This task is called NETBOOT and should be started by typing its name 
followed by an ampersand (&) on the command line. 

netboot & 

You will probably wish to place this command near the end of the system 
initialization file for the machine acting as the boot server. 

QNX operating system boot image files (osjilejiames) are kept under the direc¬ 
tory /netboot. To prevent confusion, the names of the files in this directory have 
been chosen to reflect the operating system they represent. 

os, n.n r type 

where n.n - is the version number (2.1) 

r - is the release number 
single digit 0.. 9 

type - is a hardware machine type: 

peat - IBM PC ? AT 9 PS/2 or compatible 

atp - IBM AT 9 PS/2 or compatible running in protected mode 

Hie following are typical boot filenames. 

os.2.10pcat - PC or AT, real mode, release 0. 
os.2.10atp - AT, protected mode, release 0. 

4.3 Summary 

Hie following chart summarizes the steps necessary to install QNX on a network. 
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| Configure Network Size 

netsize 

Install Networking Cards 
Set a Remote Search Order 
search 3 4-remote 

Allowing Non-super-user Access 
nacc 3 4read 4wrtte 

Create System Initialization Files fconfig/sysdnitnn 

Create a Password File If One Does not Exist 
Start the Netboot Task 

netboot & 



A poller is a program which continually sends poll messages to all active nodes in 
the network to verify their sanity. This poll message contains a list of all nodes 
which the poller believes are functional. When a node receives a poll message, it 
updates its list of UP nodes and replies with a positive acknowledgement. If the 
poller does not receive a positive acknowledgement back after several poll cycles, 
then that node is removed from the UP list. This updated list will then be sent to 
all nodes during the next poll cycle. 

When a node detects the transition from UP to DOWN on a poll cycle it will 
automatically close all virtual circuits set up between itself and that node. This has 
the effect of informing the associated QNX tasks in communication with tasks on 
that node that the remote task has died. They will then reclaim resources (close 
files, release memory,...) which may have been tied up by that remote task. 

The poller is not necessary for the network to function. Its purpose is to provide 
network wide resource reclamation in the event of a catastrophic error (machine 
crash, power failure,...) at a time when that machine has allocated resources across 
the network. The most common example would be the opening of files on a disk 
on another node. Turning the power off on a machine which is sitting idle would 
not require the poller. 
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Any node in a QNX network is capable of being a poller, however you should 

only run ONE poller in the network at a time* 

poll & - start poller 


You may wish to place the command 
alive 4-newboot 

in the system initialization file of each node which boots over the network. This 
will cause all nodes in the network to close all virtual circuits open to your node 
then mark your node as UP. It is effectively like a crash followed by an instant 
boot. The POLL command is documented in the Utilities section of this manual. 

4.5 Recovery Without the Poller 

If you elect not to run the poller, or if the poller node crashes you may close all 
virtual circuits from your node to the crashed node using the KILLJVCS com¬ 
mand. This command takes a single argument which is the node which crashed. 

The command 

kill_vcs 3 

tells the node on which the command is executed that node 3 has crashed. 

You may tell your own network administrator that a node is up or down using the 
ALIVE utility. Your local network administrator will refuse to attempt to set up a 
virtual circuit to any node it believes is down. 

alive +2 +4 -3 - set status of node 

2 and 4 as UP 

3 as DOWN 


Both the ALIVE and POLLER command contain many options which you should 
read about in the Utilities section of this manual. 



During your first attempt at setting up the network, you may encounter some dif¬ 
ficulty. The following are some tips which can aid you in diagnosing problems: 
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For purposes of example, we will assume the boot server is node 1. This means: 

• That the operating system image files ( osJUejiames ) are in the /netboot 

directory somewhere in its search order (most probably on its hard disk). 

• You have a remote search order defined, given proper network access, and 
have at least a 7conflg/sys.iiiit" file. 

• The NETBOOT task is running in the background. 

Let’s describe what should happen when you try to boot node 2: 

• The "Node 2" message appears in the center of the screen on node 2. 

• A flashing V appears just to the right of the "Node 2". 

(while it flashes, an operating system image is being downloaded) 

• The screen will clear. 

• Either [l]/config/sys.inlt.2 will be executed on node 2, or if it was not 
found, [l]/conflg/sys.init will run. 

• The "Login:" prompt will appear. 
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4.6.1 Diagnostic Tips 

Although you may not want to do the following all the time, you may need to use 

them as indicators during diagnostic sessions; 

1) If you run the NETBOOT command (on the boot server) with the verbose 

option, it will indicate on the boot server’s console when a boot request has 
occurred, by which node, for which operating system image, and also if NET- 
BOOT believes it was able to transmit it properly. For example: 

netboot +v & 


2) When you first try to get a node to boot, the contents of the /config/sys.init.fm 
file should be kept very simple. Try using the sys.init shiped on the QNX boot 
diskette or a one liner like: 

type "Hove QNX" 


3) Later, when creating more complex /config/sys.init.nn files, place the word 
verbose as the first command to execute. This will echo each command to the 
console as it executes. If the booting process stops somewhere during the ex¬ 
ecution of this file, then you will see which command is at fault. 

4) If you suspect a particular card is not functioning properly, replace it with 
another (if you can) and observe if the behavior remains the same or not. In 
this situation you should also remove any non-essential cards from your com¬ 
puter in case there is a conflict which you might not be aware of. In some cases 
you may even wish to test the card in another computer. 

5) If you are setting up a card on an existing network, you can use the TSK and 
ALIVE (if the poller is running) commands on the other nodes to see if they can 
communicate with this node. 

4.6.2 Symptom Checklist 


The machine boots from disk instead from the network. 

The card is not programmed correctly. You should select the "Boot 
from Network" option. 

The screen does not clear, and the "Node nn" never comes up. 
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REASON: The networking card was not found during the power-up ROM scan 

performed by die BIOS. You should try another card if you can, or 
perhaps another machine. You may need need to upgrade the ROM 
BIOS in your computer. 

SYMPTOM : The "Node nn" comes up, but is wrong. 

REASON: The card is not programmed correctly. 

SYMPTOM : The "Node nn" is OK, but the Y never comes up. 

REASON: Run NETBOOT in verbose mode to see if the boot server gets the 

request and if it thinks it was sent properly (indicated by an 
"OK").If NETBOOT cannot find the operating system image file, 
"Boot file not found" is printed on the console of the booting node. 

If NETBOOT does think the OS was sent properly, then the interrupt 
configuration on the card may be a problem. Try programming the 
card to use a different interrupt. 

SYMPTOM : The "Node nn" comes up, the Y flashes, the screen clears, but the 
machine hangs. 

REASON: Since the screen cleared, the operating system was most probably 

downloaded. If your characters are echoed back to you when you 
type at the keyboard, then the system is alive, but most likely hung 
either trying to find the "/config/sys.init.wii ,, file, or if it found it, 
then it might have hung on a command within it. 

If it hung trying to find it, then verify that the boot server has 
properly defined the remote search order and given network 
access for the drive on which the system initialization file resides. 

If it hung during execution of the system initialization file, try put¬ 
ting the "verbose" command at the beginning of it to have the com¬ 
mands echoed as they execute. 

Another possibility is the wrong operating system for the type of 
machine has been downloaded. 

SYMPTOM : You can’t login. 

REASON: This is probably because the password file "/config/pass" cannot be 

found. Either it does not exist, or if one does exist, it is not in your 
current search order. 
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This chapter will cover serial and parallel ports on your computer. There is also a 
special discussion on smart serial cards. You may wish to refer to the Technical 
Note called ’’Operating System Limits". 

5.1 Serial 

Terminals, modems and serial printers are connected to your computer using a 
serial port. This serial connection is referred to as an RS-232C asynchronous link. 
Some computers have 1 or 2 ports built-in while others require you to plug in an 
additional adapter card. Most manuals refer to the first two serial ports as COM1 
and COM2. There are a number of multi-port cards on the market which have as 
many as 8 serial ports on one card. With QNX, these cards allow you to support 
many users on a single machine. You can also have one or more tasks monitor 
these lines for use in a process control application. 

This section deals with "dumb" serial cards. Smartcards are described at 
the end of this technical note. 



After booting, QNX scans for serial ports at the following 10 port addresses in the 
following order. 

3F8 ( coml ) 

2F8 (com!) 

280 288 290 298 2A0 2A8 2B0 2B8 3E8 2E8 

Note: This is the default list and may be changed by running 
the OSCONFIG program. 

QNX will assign device numbers and names to each port found as follows. 

1 st - $mdm 

2nd - $terml 

3 rd - $term2 


Use the MOUNT command with no arguments to see the names and 
tty numbers recognized by the system. 


QNX Terminals 


QNX 37 



QNX does NOT poll serial lines but runs them in interrupt mode. COM1 (port 
3F8) uses interrupt 4 while COM2 (port 2F8) uses interrupt 3. A multi-port card 

generates a single interrupt for all (4 to 8) ports. You can usually select which 
interrupt is generated. QNX has, built in support for most multi-port serial cards. 

The technical support group can advise you on cards which are in use by existing 
QNX customers. 

Note that some multi-junction cards have two serial ports on one card. 

These are usually COM1 and COM2 and each port uses its own interrupt (4 or 
3). They do not share a single interrupt like a 4 or 8 port serial card. 

In a PC/AT each card must be assigned a unique interrupt, they cannot be 
shared. In a PS/2, interrupt sharing is allowed. 

By default, QNX only enables interrupt 4. To use a serial adapter which has been 
configured for interrupt 3, you must explicitly turn on interrupt 3 with the STTY 

command. 

stty inton=3 

If you wish to use an interrupt other than 3 or 4 you must tell QNX to map that 
interrupt to the serial handler by copying vector 4 into the vector selected. To 
configure a card on the AT to use interrupt 5 you would execute the command: 

stty intcp=4,5 inton=5 


If a 4 or 8 port serial card is installed, try to configure it to respond to I/O address 
280h. The 4/8 port card will only generate one interrupt for alt ports. 

If you run across a card which uses I/O ports other than those scanned by QNX, 
you can change QNX’s list by running the OSCONFIG command described in the 
QNX manual. 

5.1.2 Baud Rates and Parity 

When QNX boots, it sets the baud rate and parity on all serial ports to 1200 baud, 8 
bits and no parity. You will have to set the baud rate of your serial card to match 
that set by the terminal, modem or serial printer. For terminals and printers we 
recommend 9600 baud if possible. Modems will typically be 300, 1200 or 2400 
baud. You must also set the number of data bits to 7 or 8 and the parity to one of 
even, odd, mark, space or none. 
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Data Bits Parity 
7 even. 

7 odd 

7 mark 

7 space 

8 none Allows 8 bit data transmission 

These parameters are changed using the STTY command. For example: 

stty baud=2400 >$mdm 
stty baud=9600 >$terml 
stty baud=9600 par=even bits=7 >$tenn2 

5.1.3 Connecting Cables (DTE vs DCE) 

Most serial cards have been configured as a DTE (Data Terminal Equipment). This 
means that the electrical interface thinks that it is a terminal and it can not be 
directly connected to another terminal. It was meant to connect to a modem or a 
printer. If you wish to connect a terminal to a DTE serial port you must make a 
special cable that makes your port look like a DCE (Data Communication Equip¬ 
ment). Some cards have options to allow this. Most of the single port cards do 
not. If the card does not have this option then you must connect what is sometimes 
called a NULL modem in the serial line between your PC and he terminal. 

A NULL MODEM is a cable which interchanges some of the lines. You can make 
a NULL modem for a 25 pin serial connector as follows. Remember that to con¬ 
nect a modem or a printer you can use a straight through cable. 

The signals on the following pins must be exchanged on one of the two connectors 
to make a NULL MODEM: 

pins 2 &3 Transmit and Receive data 

pins 4 8c5 Ciear-to-send and Reqeest-to-send 

pins 6 &20 Data-set-ready and Data-terminal-ready 

The remaining pins should be connected directly from one connector to the other. 
NOTE that in most instances, not all 25 pins need to be connected. For most 
RS-232-C terminals (NOT Current Loop), only pins 2 through 8 and pin 20 need to 

be connected. 
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Terminal 

PC 

25 PIN 

PC 

Modem 

1 —..... 

1 

ground 

1 «... 

1 

3 <—. 

2 

tx data 

2 ..... 

> '2 

2 —> 

3 

rx data 

3 <—« 

3 

5 ~ 

4 

rts 

4 ..... 

> 4 

4 ———> 

5 

cts 

5 

5 

20 ———> 

6 

dsr 

6 <—— 

6 

7 -— 

7 

ground 

7 ..... 

7 

8 

8 

carrier 

g <_. 

8 

6 <——— 

20 

dtr 

20 --- 

> 20 

NULL MODEM 

CABLE 

STRAIGHT THROUGH CABLE 


There are a number of serial cards on the market that have a 9 pin connector. The 


pin assignments are as follows. 

Pin 

Signal 

1 

carrier 

2 

rx data 

■3 

tx data 

4 

dtr 

5 

ground 

6 

dsr 

7 

rts 

8 

cts 

9 

ring 


If you must connect a serial port to a device which provides only tx data, rx data 
and ground, it is a good practice to jumper the handshake lines as follows; 


ground 

ground 

tx data 

rx data 

rts 

cts 

dsr 

carrier 

dtr 
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This jumpering will only allow software flow control to be used. 

5.1.4 Setting QNX Line Editing Options 

QNX can be configured to perform line editing on input and the expansion of 
certain characters on output. The default settings are suitable for connecting a 
terminal to QNX and having a user login. 

If you wish to connect a serial printer you should disable line editing and echoing 
of input characters. 

stty -edit -echo >$printer_device_name 

You may also wish to disable one or more character expansions using the fol¬ 
lowing options to STTY: 

-etab Expand tabs to spaces set every 4. 

-ers Expand a record separator to a carriage return linefeed. 

-edei Expand a rubout to a space, backspace, space. 

Many programs, such as LIST, will automatically reset and restore these expan¬ 
sions as needed. If you leave them enabled this has the advantage of allowing you 
to directly copy text files to the printer and have them come out looking OK. 

QNX separates text lines in files with a single record separator character 
(hex le). If you do not have the ERS option enabled then this character will 
not be expanded into a carriage return linefeed resulting in output which is 
difficult to read. 

When connecting a modem for outgoing calls only, you should disable both edit 
and echo as with a printer. If you wish to support incoming calls, then leave the 
options in their default state for a terminal. You may wish to use the COMM 
program for incoming calls. It is described later on in this technical note. 

5.1.5 Flow Control 

QNX supports both software and hardware flow control on input or output. This 
can be explained with an example. 

Assume that a serial printer is connected which can print at 120 cps. A QNX 
program can send data to the printer at 9600 baud which is about 960 cps. To 
prevent loss of data the printer will tell QNX to stop sending just before its input 
buffer is full. It can do this in one of two ways. With software flow control it will 

send an XOFF (Ctrl s) character telling QNX to stop sending. When it is ready for 
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more data it will send an XON (Ctrl q) telling QNX to resume output. With hard¬ 
ware flow control it disables one or both of the hardware signal lines called CTS 
(ciear to send) and DSR (data set ready). When it is ready for more data these 
lines are re-enabled. Most terminals and printers can be set to use either hardware 
or software flow control. On a terminal, software flow control is nice in that you 
can type Ctrl s at the keyboard to stop QNX output and then a Ctrl q to resume. 
This is the default set on the console/keyboard. With a printer there is a small 
danger that you might get an XOFF but not an XON. This can be fixed by turning 
the printer off and on line (the printer should send an XON when it goes online) or 
by telling QNX to continue anyway using the STTY command. 

stty -paged >device_name 

When QNX is blocked on output because of flow control, it is referred to as 
"paged". 

Input flow control is the same process, but in the oposite direction. QNX will send 
an XOFF/XON (software) or toggle RTS/DTR (hardware) to prevent its input 
buffer from overflowing if data is received faster than a QNX application can 
process it. 

The defaults at power up are software flow control on output only. You can 
change these using the following STTY options. 

+|-hfiow - Select software or hardware flow control. 

+Inflow - Enable/disable input flow control. 

+|-oflow - Enable/disable output flow control. 



To login on a terminal, you must ensure that the parity and baud rates are set cor¬ 
rectly, then type a Ctrl-z. If you do not get a login prompt, try typing a Ctrl-x 
(delete any garbage in the input buffer) and a Ctrl-q (unpage incase a Ctrl-s has 
paged output). If this fails, then type some letters. If they fail to echo, you may not 
have properly configured your serial port(s). 

5.1.7 Logging In From A Modem 

You must configure your modem to auto-answer mode and simply follow the 
procedure for logging in to a terminal. While this works it has two major disad¬ 
vantages. 

L If you hang up, or the line drops, you will not be logged off. 

2. You must always access the modem at the correct baud rate. 


QNX 42 


Terminals 



With 300/1200/240(1 baud modems popular, you may not know which 
baud rate to select. 

To solve these problems, you may wish to run the COMM command. This 
program will determine and set the baud rate and parity for the remote user. The 
COMM command is described in the utilities section of your QNX manual. It 
supports both dumb modems and hayes compatible modems. When carrier is lost, 
COMM will kill off your program, effectively logging you off. To detect loss of 
carrier it is important that the modem raise and lower the carrier detect line (pin 8) 
and that your modem cable connect that line. 



To place an outgoing call you will use the QTALK program. Please refer to the 
QTALK documentation for details. If you require a more advanced terminal 
emulator you may wish to purchase an extremely slick product called QTERM. 

5.2.1 Problems 

Most problems connecting serial ports can be traced to one of the following: 

1. Interrupts on the serial card are not configured 

properly or two cards are sharing an interrupt. 

2. The I/O port on the serial card is not configured 
properly or two cards are sharing an I/O port. 

3. The cable is incorrect. You may need a straight through 
cable or one that crosses some of the signal lines. 

4. The baud rate is not correct. 

stty bmd=baud_rate >%device_name 

5. You have not enabled interrupts if the card uses an 
interrupt other than 4. The symptom of this is a single 
character being echoed. 

stty mton=int__num 

5.3 Parallel 

Connecting a parallel printer to QNX is very easy. You do not need to worry about 
interrupts, flow control or special cables as you do for serial connections. QNX 
supports up to 2 parallel ports which are called 

$lpt, $lpt2 
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It is rare to see more than one or two in a system. 

5.4 Smartcards 

A smartcard is a multi-port serial card with an onboard processor and a large 
amount of memory for buffering incoming and outgoing data. There are no inter¬ 
face standards for smartcards, as there are for dumb cards, and you must run a 
custom driver to use these cards. These cards may be more expensive than dumb 
serial cards. They should be considered when: 

° You have more than one channel of input data at 9600 baud. 

® You have input data which cannot be flow controlled and comes 
in bursts greater than 250 characters. 

° You are performing nearly continuous output at 9600 baud and 
must maintain that data rate on several channels. 

° You need to support more than 10 serial ports. The smartcards 
typically allow up to 4, 8-port cards in a system, for a total of 
32 possible serial ports. 

If you are only connecting terminals to QNX, then you probably do not need a 
smartcard. If you are unsure, contact QNX technical support for some guide lines 
as well as an up-to-date list of supported smartcards. The smartcard drivers are 
available from the manufactures (the best choice) or from QUICS (the QNX up¬ 
date system) for download. In many cases, full source code for the driver is also 
available. The driver runs as a background task. A typical invocation of a driver 
would look like this: 

smartcard a=d000 i=5 p=3O0 & 

Start driver to talk to a card with: 

dual ported memory at segment d000 

interrupt 5 

I/O port 300 

Wait a few seconds for the card to be initialized and type the MOUNT command 

with no arguments to see the new set of device names. 


QNX 44 


Terminals 



6. Devices 

QNX provides a sophisticated terminal handler for all character devices attached to 
it (keyboard, display, serial communication ports). This chapter is a summary 
suitable for end users. 



The following information concerns itself with the default options set up for both 
the console keyboard and attached terminals in a multi-tasking system. Due to 
keyboard limitations of many terminals, some keys and options will apply to the 
console keyboard only. 

6.1.1 Alt, Shift and Ctrl 

These three keys do not generate data themselves, but modify the data generated 
by other keys. 

The shift key is used to type upper case letters and the symbols shown on the upper 
positions of the keys with dual markings. 

The Ctrl key is used to generate the control codes defined in the ascii character set. 

The Alt/Compose key, when used as a shift, will turn on the eighth data bit for any 
key combination pressed. When typed as a data key it sets up a two character 
compose sequence. Compose characters allow you to enter extended codes for 
foreign language characters and special symbols. This is described later in this 
section. This key is only available on the console keyboard and special QNX com¬ 
patible terminals. 

The entire character set for the console keyboard is contained in appendix A. The 
first table will apply for most terminals. The second table is specific to the console 
keyboard and special QNX compatible terminals. 

Users with a foreign language keyboard on their PC should refer to the KEY¬ 
BOARD command in the utilities section of this manual. 

6.1.2 Caps Lock, Num Lock 

These three keys are used to select a particular input mode. 

The Caps Lock key converts all lower case letters to capital letters until you press 
it again. This key is available on most terminals. 


QNX Devices 


QNX 45 



The Num Lock key lets you type the numbers on the keypad without having to 
shift. If you do use the shift key in this mode, it will allow you to access the scroll 
(arrow) codes on the bottom of the keys. This key exists on PC keyboards which 
share the keypad for numbers and cursor keys. Like the Caps Lock key, Num Lock 
key is a toggle. Typing the key a second time will turn off Num lock mode. 

If you run the CLOCK program, it will display the state of the Caps Lock, Num 
Lock and Alt key in the upper right hand comer of your console display. 

6.1.3 Type-Ahead 

The QNX Operating System provides full type-ahead with echo and line editing. 

As long as QNX is functional, your input keys will be seen and remembered. As a 
general rule, whenever you enter a line, there will be a program waiting for input 
which will consume it. You act as the producer and the program acts as the con¬ 
sumer of input lines. If there is not a program waiting on the keyboard, you may 
still continue to type input lines which will be saved until a program (usually the 
command interpreter(SH)) asks for them. For example, if you wanted to execute 4 
programs, and each program took between 1 and 5 minutes, you could type all four 
commands one afler another and go for a coffee while they finish. 

The operating system has a limit of 254 characters in the type-ahead buffer. QNX 
will stop echoing your characters if this limit is exceeded. This can be mistaken 
for a software crash. If you keyboard does not echo, first try typing a Ctrl-x to 
delete the last line in the input buffer. If you get echo but no command output try 
typing a Ctrl-q to cancel output flow control. This can occur if you type or your 
terminal sends a ctrl-s. If this does not help, refer to the chapters on "Connecting 
Terminals To QNX" and "Tips On Using QNX". 

6.1.4 Line Editing 

Your keyboard/terminal can operate in one of two modes called EDIT mode and 
RAW mode. In RAW mode, every character typed is immediately given to the 
program asking for input. The program itself acts on each character received. The 
full screen editor runs in this mode. In EDIT mode, when you enter characters on 
a line, they are not passed to any program waiting for input until you type the car¬ 
riage return key. This allows you to correct any typing mistakes you may make. 
The keyboard (terminal) input routine examines each character you type and 
recognizes several keys as special. The command line interpreter (SH) runs in 
EDIT mode. The following keys are special in EDIT mode. They are summarized 
in appendix A. 

RUB OUT (PC: back-arrow TERMINAL: Del or Rubout) 

This key deletes the last character typed. The cursor will move one position to the 
left, erasing the character at that position. Only characters which are typed by the 
user will be erased. The cursor will not back up over a system prompt. 
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CANCEL (Ctrl-x) 

This key deletes the entire line. 

LEFT/RIGHT (PC: left, right arrows TERMINAL: backspace, n/a) 

These two keys allow you to move your cursor back and forth over any text on 
your line, changing it if desired. On a terminal these keys must be defined using 
the STTY command since there is no clear standard. Most terminals support a 
backspace key but some may not support a non-destructive forward space. 

DELETE (PC: Del key TERMINAL: Ctrl-k) 

This key deletes the character at the current cursor position. The rest of the line 
will slide over to fill the gap. On a terminal this key must be defined using the 
STTY command. 

INSERT (PC: Ins key TERMINAL: Ctrl-n) 

This key toggles insert mode. In insert mode any characters that you enter will be 
inserted before the character at the cursor. Insert mode is always turned off when 
you enter a CARRIAGE RETURN a BREAK or a CANCEL. On a terminal this 
key must be defined usin** the STTY command. 

TAB (tab key or Ctrl-i) 

This key will enter a tab character in your buffer, and echo the required number of 
spaces to move you to the next tab stop. In QNX, tab stops are set every four 
columns with the first stop set in column five. If you try to RUBOUT a tab 
character, you will only remove one displayed space on your screen even though 
the TAB may have been displayed as several spaces. The TAB character in your 
buffer will have been deleted. It is your display which expanded the TAB but 
failed to un-expand it on the RUBOUT. 

CARRIAGE-RETURN 

This key causes the entered line to be made available to the user program. Carriage 
returns are automatically mapped into RECORD SEPARATORS (hex le) by 
default. QNX separates lines by a single record separator character in text files. 
This differs from DOS which separates lines will two characters (carriage return 
and linefeed) and Unix which uses a single linefeed. 

PAUSE (Ctrl-s) 

Suspend further system output to the terminal (until Ctrl-q). 

CONTINUE (Ctrl-q) 

Continue allowing any system output to be displayed. 

BREAK (PC: Ctrl-Break TERMINAL: Ctrl-c or BREAK key) 

This key halts execution of the currently running program which is associated with 
the terminal. Any opened files will be closed, and all memory will be returned to 
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the operating system. Note that some programs (such as the full screen editor) are 
capable of trapping BREAK, preventing program termination via this key. 

ESCAPE (Ctrl-z) 

This key suspends (but does not kill) all running tasks associated with this terminal 
and creates a new shell allowing you to enter commands. This key allows you to 
escape from any program which has not defined its input stream to be RAW. 

When you terminate the shell with a Ctrl-d you will return to the program you 
suspended. Do not use Ctrl-z as a break even though the immediate effect (you get 
a $ prompt) is similar. You will eventually mn out of task entries or memory since 
the suspended programs remain around. Programs which do run unedited (ED) 
may have been designed to look for the Ctrl-z and invoke a shell. 

REBOOT (PC: Ctrl-Alt-Shift-Del - 4 keys held down) 

This combination will cause QNX to reboot itself. Your open files are NOT 
closed, and any which were open for write will be left busy. You can get rid of 
them by using the ZAP command. This method of restart should only be used 
when you have no running programs or in the rare event that QNX should "check 
out" (CRASH). 

DEBUG (PC: Ctrl-Alt-Esc - 3 keys held down) 

This combination will suspend execution of your program and invoke the low level 
assembly debugger if it has been loaded. If the debugger has not been loaded then 
this key combination is ignored. 

6.1.5 Compose Characters 

The Alt/Compose key on your PC is a dual function key. When used as a shift it 
will turn on the 8th data bit of the shifted character. For example 

a - generates hex code 61 
Alt a - generates hex code El 


If it is depressed then released, WITHOUT typing any other key, it sets up for a 
two character compose sequence. The next two characters are combined into a 
single 8 bit character code. Appendix A contains a list of compose key trans¬ 
lations. The following brief table lists a few. 


Alt (release) p i 

—> 

Alt (release) + - 

—> 

Alt (release) e 9 

--> 

Alt (release) 1 2 

--> 

Alt (release) b a 

—> 


pi symbol 

plus or minus symbol 
e accent grave symbol 
hex 12 character 
hex ba character 
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The last two illustrate the inputting of exact hex values. 

If a program wishes to accept compose characters and differentiate them 
from function and cursor keys it should enable option EFUNC. This will 
precede all function and cursor keys with a hex FF. This is necessary since 
the codes returned for function and cursor keys overlap the composed charac¬ 
ters. Programmers should refer to the documentation on the GET OPTION 
library routine in the C compiler manual. 


6.1.6 Input Gate 

A unique feature of the QNX terminal handling software is termed the INPUT 
GATE, which prevents output from being mixed with user input on the display. 

If the INPUT GATE option is enabled, the operating system will stop all program 
output to the display while you are entering a line of text. When the line is ended 
with a carriage return, or the user deletes the entire line (via CANCEL or 
RUBOUT), system output to the terminal will again be allowed. This option may 
be turned off using the STTY command. 

stty -igate 


Programmers should note that this option is ignored when you turn off the 
EDIT option. The option is meant for the console and users connecting to 
terminals. It is not used for serial ports configured as raw communication 
lines. 


6.1.7 Recalling Command Lines 

Due to QNX’s circular 256 character buffering scheme on input, it is possible to 
back up or move forward in the buffer recalling previously entered lines. The 
number of lines you may back up is determined by the length of each input line. 
Editing a line you have backed up to may overwrite part of the following line. You 
should think of the up and down arrow as a means of rolling backward and forward 
through your typed lines. On a terminal you will have to define these keys using 
the STTY command. 


QNX Devices 


QNX 49 



RECALL PREVIOUS LINE (PC: up arrow TERMINAL: Ctrl-u) 

This key will redisplay the previously entered line, allowing you to edit it if neces- 
sary. Typing it again will recall the line previous to this and so forth. Warning: 
Attempting to recall a line after a command which runs without line editing (Full 
Screen Editor, Talk) may result in garbage being displayed. 

RECALL NEXT LINE (PC: down arrow TERMINAL: Linefeed or CtrLj) 
This key is the opposite of the up arrow and moves you forward through your type 
ahead buffer. These keys must be defined using the STTY command if they are to 
be used on an attached terminal. 

6.2 Terminal Output 

6.2.1 Attributes 

Your console display supports several special attributes. 

- inverse video 

- underline 

- blinking 

- intensify 

- colour 

These attributes may be accessed in QNX by sending special control character 
sequences to the display. These sequences apply to the console only. It is unlikely 
that an attached terminal on QNX will support the same escape sequences to access 
their special attributes. QNX’s escape sequences were chosen to provide a user 
friendly interface, not for compatibility with any manufacturer’s line of terminal 
equipment. 

Users interested in writing programs which are terminal independent should 
read the documentation on the TCAP utility and library. 

Not all machines which QNX supports will have the same set of display at¬ 
tributes. QNX will map and support these attributes in a machine independent 
manner. Selecting an attribute which does not exist will have no effect. 

6.2.2 Output Escape Sequences 

The QNX video display driver treats the Ascii ESC code (hex character lb) as a 
special control code. The character following an ESC is examined, and if recog- 
nked will cause some control function to be performed. An unrecognized 
cha , r ?S^ followin § an ESC win be passed to the display unmodified, so to print a 
real ESC character on the screen, you may send two ESC codes 
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Following is a list of the ESC sequences which are recognized by the QNX display 
driver. Note that due to hardware limitations some combinations may not be pos¬ 
sible. In particular inverse and underline are mutually exclusive on the IBM 
monochrome display. Since the QNX shell echoes each received character you can 
experiment with these sequences by simply typing them in. The most commonly 
typed sequence is a Ctrl-1 which will clear the screen. 


QNX Devices 


QNX 51 



Esc ( 


Esc) 

Esc [ 

Esc ] 

Esc { 

Esc} 

Esc < 

Esc > 

Esc A 
Esc 1 
Esc C 
Esc D 
Esc E 
Esc F 
EscH • 
Esc 1 
Esc J 
Esc K 
Esc 1 
Esc 2 

Esc 8 
EscS 
Esc R 
Esc @fc he 


Esc I fc he 


Esc - re 


Esc Y re 


Turn on inverse video mode. This will 
also swap the foreground and background 

colours set by the ESC @ sequence 
Turn off inverse video mode 
Turn on underline mode 
Turn off underline mode 
Turn on blinking mode 
Turn off blinking mode 
Turn on high intensity mode 
Turn off high intensity mode 
Move cursor UP (no wrap) 

Move cursor DOWN (no wrap) 

Move cursor RIGHT (no wrap) 

Move cursor LEFT (no wrap) 

Insert line 
Delete line 
Move cursor HOME 
Reverse linefeed 
Clear to end of screen 
Clear to end of line 
Switch to console 1 
Switch to console 2 
etc... 

Switch to console 8 
Save colour and attribute information 
Restore colour and attribute information 
Define the foreground and background colour 
of displayed characters. Both/c and be 
represent a single digit taken from the 
colour table below. 

Sets the fill colour which is used for 
the bottom line when scrolling and the entire 
screen when clearing via form feed. 
fc is the colour of the cursor, be is 
the fill colour 

Position cursor at the screen coordinates 

(r, c) which are given by the two characters 

following the R is the row (0-24) 

and c is the column (0-79). Both r and c are 

offset by hexadecimal 20 (a space). Therefore, 

re = <SPACExSPACE> is row zero, column zero 

Same as ESC = 
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As an example, the sequence 

Esc@71Esc!71 

will set your character and fill attribute to white on blue. 


digit colour 
0 black 

1 blue 

2 green 

3 cyan 


colour 
red . 
magenta 

6 brown 

7 white 


COLOUR CODES # 

digit 
4 


You should set your colour preference using ESC @ and ESC ! in your sys.init file 
and follow it with an ESC S to save it away. All QNX applications which play 
with the colour will print an ESC R to restore the saved colour before exiting. 
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In addition, the following characters will cause some special action to be per¬ 
formed, rather than printing a character on the display... 


CR 

Carriage-return. 

Move cursor to column 0 of current line 

LF 

Line-feed. 

Move cursor down 1 position, and scroll the 
screen up 1 row if necessary. 

FF 

Form-feed. 

Clear the display to the background attribute 
defined by ESC ! sequence. Cursor returns to top left 
comer (0,0). 

BS 

Back-space. 

Move die cursor left 1 position. Wrap around 
to the previous line if necessary. 

BELL 

Bed. 

Generate a tone for a fraction of a second. 

HOME 

Move cursor to top left comer of screen. 

up-arrow 

Move cursor up one position. 

Wrap around to bottom if necessary. 

down-arrow 

Move cursor down one position. 

Wrap around to top if necessary. 

left-arrow 

Move cursor left one position. 

Wrap to end of previous line end if necessary. 

right-arrow 

Move cursor right one position. 

Wrap to beginning of next line if necessary. 
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7. Full Screen Consoles 

Virtual consoles give you the ability to switch between several tasks, each running 

on a different virtual console. For example, a developer may choose to edit 
programs in one console, compile programs in another console and execute them in 
yet a third console. Multiple consoles offer a definite advantage over running 
programs in background in that you may examine your output and gain control at 
any time. An advanced work station might run a VT1GG emulator, 3278 emulator 
and another QNX application in three consoles, all concurrently, with the ability to 
rapidly switch between applications. 

QNX can support several virtual consoles on your PC’s physical screen. Each 
virtual console is one full screen and may be thought of as a console to which you 
may attach your keyboard. Your keyboard is always attached to the console which 
is being displayed. The other consoles may still receive output data from tasks. 

7.1 Mounting Consoles 

When QNX boots, it assumes only one console. You must explicitly MOUNT 
every other console you wish to use. 

By default* QNX has a built-in Console Driver which will work with CGA and 

EGA in text mode. Other Console/Graphics Libraries are available which support 
text consoles in 43x80 mode, these are: 

/drivers/glib.ega - IBM Enhanced Graphics Adapter, 
/drivers/glib, vga - IBM Video Graphics Array. 

If you wish to use consoles in these non-standard text modes you must mount the 
proper Console/Graphics Library before you mount any of your extra consoles. 

If you mount them afterwards you will be limited to a screen size of 25 by 80. 

The operating system allocates system memory to store each of the consoles that 
have been mounted when they are not displayed. When you mount your first 
extra console, QNX will query the Console/Graphics Library which is mounted at 
that time, to find out what maximum amount of space is required to store a console 
(for example, the default 25x80 needs 4K, while 43x80 requires 6.8K). Once the 
buffer size has been determined, it is memorized and used for all other subsequent 
console mounts. 
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QNX supports many standard devices. To determine exactly how many devices 
your current version supports you should refer to the Technical Note called 
"Operating System Limits". Each device has two names. A $tty nn which iden¬ 
tifies device nn and a symbolic name like $mdm which can also be used to 
reference the device. For example, $tty3 is usually associated with $mdm. The 
following illustrates how the device entries are intended to be used with physical 
devices: 


0 $con » keyboard 

7 $term4 - serial £ 

1 $lpt - parallel 1 

8 $term5 | 

2 $Iptl - parallel 2 

9 $term6 j 

3 $mdm - serial 1 

10 $term7 j 

4 $terml 


11 $iermg j 

5 $tenn2 


12 $tenn9 - serial 10 

6 $term3 - serial 4 



In practice, not all devices are used. These unused device entries may be con¬ 
verted into virtual consoles using the MOUNT command. 

For example, the following commands will create three new consoles for a total of 
four including $con. The device number of the device entry to re-use may be given 
(eg. 2 for $lpt2, 5 for $temi2, etc) followed by a new name to assign to the con¬ 
sole. If you do not specify the device, then a free one will be selected for you. If 
you specify a device, be VERY careful to specify only unused device numbers. 
Typing the MOUNT command with no arguments will display the devices in your 
system. 

mount 


The new name may be up to five characters in length. 
Device not specified Device specified 


mount console $conl 
mount console $con2 
mount console $con3 


mount console 2 $conl 
mount console 11 $con2 
mount console 12 $con3 


You will wish to place MOUNT CONSOLE commands in your system initializa¬ 
tion file so they will be executed automatically each time you boot. 
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7.2 Switching Consoles 

Holding down the Ctrl key, the Alt key and then pressing the large plus key on the 

keypad will step you to the next console while a Ctrl-Alt minus (keypad) will step 
you to the previous console. 

People may enter a particular console by holding down the Ctrl key, the Alt key 

and then typing the console number (1 through 8). 

Programs may switch the displayed console by writing an escape sequence to any 
of the consoles: 

ESC 1 - displays the first console $con 
ESC 2 - displays the second console 
ESC 8 - displays the eighth console 
etc... 

NOTE: This second scheme may seem to work if typed in by users, but data 
characters are left in the device buffer, which usually confuses the application that 
reads them. 

At the time of this printing, certain EGA video cards on the market perform a 
bit of magic allowing them to auto-switch between several graphics modes. 
They also allow you to connect a monochrome or CGA monitor to the con¬ 
troller while in EGA compatability mode. The card does all the grayscale 
interpretation required to make it work. They implement this cleverness by 
generating an HO check which generates a NMI (non-maskable-interrupt) 
which they vector into their ROM BIOS on the card. This trick does NOT 
work in protected mode and will cause the operating system to fault, usually 
the first time you attempt to switch consoles. 

Fortunately, you can usually disable the INTELLIGENT capability of these 
cards and make them BE a MDA, CGA, HGA or EGA controller connected 
to the appropriate monitor type. 

Any program may be executed in the active (displayed) console and will behave 
as expected. However, some programs which write directly to the screen memory 
or use the BIOS calls (int lOh) may cause problems if you switch to another con¬ 
sole while they are executing. The rule of thumb to use in these cases is never 
switch to another console unless you are sure these programs are not going to try to 
print to the screen while you are in the other console. Programs which use the 
QNX I/O facilities or the high speed video interface will not have a problem. This 
includes all QNX Software Systems’ utilities and products. 
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The stty command supports a +hold option which will hold a task from 

running unless it is the active console. This may be useful for a console in 
graphics mode where applications always write directly to the screen memory. 
Programmers can control this option from within their programs. 


7.3 Initiating Commands in Other Consoles 


Typing a Ctrl-z in a new console will cause the login prompt to be displayed just as 
it would for any terminal. 

Occasionally it may be necessary or convenient to automatically initiate a com¬ 
mand in the other console. This can be accomplished using the ONTTY command. 

mount console 2 coni 

ontty 2 login 
OR 

ontty 2 application 

7.4 Consoles and Graphics 

The default Console Driver which is part of the operating system, does not support 
any graphics. However, as mentioned above, there are several Console/Graphics 
Libraries which can be mounted to replace and/or augment its capabilities. These 
support graphics capabilities through the compiler library interface. 

These allow you to have 1 console in graphics mode at any one time, and some 
allow you to switch consoles when in graphics mode, while others prevent it: 

/drivers/glib.hga - Hercules Graphics Adapter. 

• Text mode [ 25 by 80 monochrome ], 

• Graphics mode [ 720 by 348 monochrome ]. 

/drivers/glib.cga - IBM Colour Graphics Adapter. 

• Text mode [ 25 by 80 with 16 colours ]. 

® Graphics mode [ 320 by 200 with 4 colours ]. 

[ 640 by 200 with 2 colours ]. 

/drivers/glib.ega - IBM Enhanced Graphics Adapter. * 

® All modes from CGA Library. 

® Text mode [ 43 by 80 with 16 colours ]. 
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•Graphics mode [ 640 by 350 with 16 colours ]. 

/drivers/glib.vga - IBM Video Graphics Array. * 

• All modes from EGA Library. 

• Text mode [ 43 by 80 with 16 colours ]. 

• Text mode [ 50 by 80 with 16 colours ]. 

• Graphics mode [ 320 by 200 with 256 colours ], 

• Graphics mode [ 640 by 480 with 16 colours ]. 

* Cannot switch consoles when In graphics mode. 

For more information see the Technical Note called "Console Shared Library". 
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8. Files 


8.1 File Names 

Like most operating systems, QNX stores information on disks in files. You iden¬ 
tify a file by its name. On QNX, a filename may be from 1 to 16 characters chosen 
from the set of: 

- the letters of the alphabet 

- the numbers 0 through 9 

- the period V and the underscore 9 _ 5 

- hex characters 80 through AF (foreign characters) 

Upper and lower case letters are distinct. The file "Report" does not have the same 
name as the file "report". Some examples of good and bad filenames follow: 

John Doe Bad: contains a space 

27=d Bad : contains a dash 

John Doe Ok 

123.7 Ok 

Ok 

teste Ok 

Unlike some operating systems, the period is not treated as an extension se¬ 
parator by the QNX file system. It is just another possible character making up a 
filename. To improve clarity, the user may adopt the convention of suffixing 
filenames with an extension (a period followed by a few characters). The exten¬ 
sion is NOT enforced by the file system, only the user and perhaps the commands 
that operate on files. In particular, the C compiler assumes that a C program that it 
has been asked to compile ends in ".c". If asked to generate an object file it creates 
a file with the ".c" replaced by a ".o". 

8.2 Structure of Files 

A file is regarded by QNX as a featureless, randomly addressable sequence of 
bytes. No other structure of files is assumed by the operating system. Commands 
which operate on files will in general impose their own structure. For example, 
commands which operate on text files (p, ed, size etc...) assume that a file consists 
of variable length lines, with each line terminated by an ascii RECORD SE¬ 
PARATOR character (hexadecimal value IE). 

A file may vary in size from 1 to 1,099,511,627,771 bytes (about 1 terabyte). A file 
cannot be larger than the disk which contains it. 
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The smallest unit of storage allocation for a file is one 512 byte disk sector. Files 
need not be contiguous or preallocated to their maximum foreseeable size. QNX 
will enlarge a file's size as required and if possible* allocate contiguous space for 

it 

There is a file called ’’bitmap" on each disk which contains the sector allocation of 

the disk. You may display this file in hexadecimal format using the "dump" com¬ 
mand or pictorially using the query command. 

dump 3:/bitmap 
OR 
query 3 

query 3 +d 

The total number of files a user may have on a disk is only bounded by available 
disk storage. 

8.3 Directories 

^ J sailor! O 

there is a type oi nle maintained oy me upeiaung system ^dncu a. uu ceiuty. 
Directories contain the mapping between the names of files and the files them¬ 
selves and thus impose a structure on the file system as a whole. Each user has a 
directory of files and is free to create subdirectories to contain groups of files 
which are related. A directory may be read by the user, but may only be written by 
privileged programs and as such, is controlled by the operating system. A direc¬ 
tory may contain a maximum of 32,000 files, however, if it contains subdirectories 
then each subdirectory may also contain 32,000 files. This rule is then applied to 
the subdirectories. For all practical purposes the number of files you create will 
only be limited by the amount of disk space you have available to save their data. 

The structure of the file system is hierarchical and is often called "tree structured" 
since diagrams depicting it look like inverted trees with their root at the top. To 
clarify this, lets consider an example where a user (gord) has three directories; one 
for C programs, one for Basic programs and one for business documentation. His 
file structure would look like Diagram 3.1. 
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gord 


basic 


test 


doc 


gamel game2 mortgage report 1 report2 


Diagram 3.1 


The "leaves" (test.e gamel, etc..) ar & files and the internal nodes (gord, c, basic, 

and doc) are directories. Let’s complicate our example and assume the user wants 
to separate his C game programs from his C business programs. The user also 
generates a series of reports each month and wants each of the monthly reports 
kept separate. This may be achieved by the structure in diagram 3.2. 


basic 


test 



~1 

doc 


r 


games 


s:.ness j^n f^b ... d«ic 


gamel 


g anas 2 


business J| 
mortgage month__end 


month end 


Diagram 3.2 
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Finally, let's also subdivide the directory doc into years (diagram 3.3). 


doc 


1986 


’—I 

1987 


i-r~ 

jan feb ... 


dec 


I— - 1 — 

feb ... 




dec 


month__end month__end month_end month__end month__end month end 


Diagram 3.3 


Note that you can use the same filename for different files under different direc¬ 
tories. The file system allows you to structure your files in a natural hierarchical 
arrangement. To achieve this with a flat file system would be very awkward. 

The previous examples have dealt with userid "gord". Since a disk may contain 
many userids, "gord" is in fact just a directory under another directory called 
"user". A three user disk is illustrated in Diagram 3.4. 




dan 


user 


gord 


bill 


other directories 


Diagram 3.4 
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The V’ at the top is a very special directory called the ROOT directory and each 
disk has one. Your Boot diskette contains directories under the root as illustrated 
in Diagram 3.5. 


I 



sys .init 


inform .. . 


disk .at 


Diagram 3.5 


Executable commands are kept under the directory "cmds" and configuration files 
are kept under the directory "config". Explain files are kept under the directory 
"expl". Disk drivers are under "drivers". 

8.4 Pathnames 

When you specify a file to QNX, you must present it in a form which uniquely 
identifies it within the hierarchical directory structure. This form is called a 
pathname and consists of a sequence of directory names separated by slashes, 
and ending in a filename. For example the file "Is" under the directory "cmds" 
could be written as the pathname 

/cmds/ls 

Likewise, the file "month_end" under the directory "1987" under the directory 
"jan" in diagram 3.3 could be written as the pathname 

/user/gord/doc/1987/jae/month_eiid 


The leading slash indicates to QNX that it should begin its search at the ROOT of 
the file system on your disks. In the "month_end" example, it will start its search 
on the first drive in your search order and look for the directory "user". If it fails to 
find it, it will then look on the next drive and so on for each drive in your search 
order. Once it locates "user" at the ROOT of a disk, it will look in that directory 
for the directory "gord", and if successful, it will look in directory "gord" for direc¬ 
tory "doc" and so on until it finally locates the file "month_end". 
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If you are opening a file for write, once the system has matched a directory on a 
disk (ie: "user" in this case), it will not restart its search on another drive if it fails 
to find a subdirectory or the file on its search down the tree. This behavior is only 
important if you have two disks with a directory by the same name at the ROOT. 
QNX solves this ambiguity by always stopping its search on the first disk on which 
it finds a match at the ROOT. This is not true for files being opened for read, 
read/write or execute. In these cases, the search will continue across all drives 

fnr- Qirs ATOPt 

JLOUJvlIig IU1 ail CAaCl JLJLJLclldl. 

The default search order of your drives depends on how you boot. 

Boot Search Path 

floppy 1st floppy, 2nd floppy if present 

hard disk hard disk only 

network node from which you booted. 

You may change this using the SEARCH command. For example if you had a 
ramdisk as drive five and a hard disk as drive three you could tell QNX to search 
drive five first by issuing the command: 

search 5 3 

Refer to the SEARCH command in the utilities section of your binder for more 
information. 

8.4.1 Specifying a Drive as Part of Your Pathname 

You can override QNX’s sequential search of your disk drives and lock onto a 
particular drive by prefixing your filename with a drive number followed by a 
colon (:). As an example 

backup 2:/user l:/user 

would invoke the backup command with the directory "user" on drive 2 as the 
source and the directory "user" on drive 1 as the destination. The command 

backup 1:/ 2:1 +all 

would back up all structure on the disk in drive 1 onto the disk in drive 2. Finally, 
the command 

dump 2:/bitmap 

would only look on drive 2 for the file "bitmap" under the ROOT. 
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The previous pathnames all began with a slash and cause a search to be made star¬ 
ting at the ROOT of the disk. If you leave off the leading slash, the search will be 
made starting at your current directory. When you log in, your current directory is 
set to point to the directory you logged into. For example, if you logged into "gord" 
and gord had a file named ’’costs”, you could name it via its full pathname starting 
from the root 

/user/gord/costs 

or its relative pathname starting at your current directory 
costs 

When QNX memorizes your current directory, it does more than just remember a 
pathname. It remembers the drive and block number on the disk of your current 
directory. In a QNX network the node number is also remembered. This results in 
very fast access to files accessed by this method. In practice you will find that 
90% of your pathnames will be relative, NOT absolute from the ROOT. 

If at any time you need to specify your correct directory in a utility (such as 
BACKUP), it may be indicated with a null string (""). This is also true when 
opening the current directory from a program. 

backup "" /dir - backup current directory to /dir 


8.5.1 Changing Your Current Directory 

QNX provides a command to allow you to change your current directory to point 
to any directory on a disk. The command is 

cd pathname 

where "cd” stands for "change directory". The pathname should end in a directory 
NOT a filename. For example, lets say you wanted to work on your 1987 month 
end report for January. Using the structure illustrated in Diagram 3.3 you could 
reference the file "month^end" by 

/user/gord/doc/1987/jan/month_end 

or if you had logged into userid "gord", you could access it relative to your current 
directory by 
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doc/1987/j an/month_end 

If you intend on typing this pathname more than once you should probably change 

your current directory to 

cd doc/1987/jan 

anti leieience me me da 
monthend 

At any time you may return to die directory you logged into by executing the CD 

command with no argument. 

cd - will return to login directory 

You can print your current directory using the PWD command, 
owd - will print current directory on your screen 



QNX allows you to move up the file structure by preceding your pathname with 
up-arrows ( A ). Each up-arrow moves you up one directory level. If your current 
directory was at 

/user/gord/doc/1987/jan 

you could reference your February monthend file as 
A feb/month_end 

and your 1986 jan month_end file as 
A A 1986/jan/ monthend 
Finally, you could "cd" yourself to "gord" with 
cd AAA 

which will move you up three levels. 
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8.7 File Attributes and Permissions 

Each QNX file has an attribute field and two permission fields associated with it. 
Each field acts as a mask or a filter limiting access to a file. 

The attribute field limits the access modes which may be applied to the file by any 
user INCLUDING the OWNER of the file, the GROUP LEADER and the SUPER 

USER. 

The group permission field limits the access modes which may be applied to the 
file by users which are in your group. 

The other permission field limits the access modes which may be applied to die 
file by other users. 

Changing permissions allows you to control access to include 

- yourself only 

- users which are in your group 

- users which are not in your group 

- all users 

Opening a file performs the attribute and permission checks. If any check fails, 
then the open will fail with a ’’permission denied" violation. The following 
diagrams illustrate the sequence of checks made. 
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ACCESS BY 
OWNER,OF FILE 


attr 


I N 

deny access 


Y 


grant access 


ACCESS BY 


USER 


:N SAME GROUP 


attr 


l N 

deny access 


Y 


group permissions 


N 

deny access 


ACCESS BY 

USER IN MOTHER GROUP 


attr 


I m 

deny'access 


Y 


other permissions 


N 

deny access 


Y 

grant access 


Y 

5 grant access 
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The attributes/permissions of a file are: 


READ 

WRITE 

APPEND 

EXECUTE 

MODIFY 


- You may open the file for read. 

“You may open the file for write. 

Previous contents are lost. If you 
do not write to the file it will be 
removed when you dose it. This 
also gives delete capability. Files 
may be opened for read/write in which 
case the previous contents are not 
affected by the open operation. 

- You may open the file for append. 

Any new information you write will 
not overwrite any current information 
but will be added to the end. 

- You may open the file for execute. 

This allows you to execute the file 
as a load module or a command file 
without the sh. All QNX commands 
have the attribute of execute. 

- You may modify the attributes/permissions 
of the file. 


When a new file is created it will by default have the attributes and permissions of: 

attributes: READ WRITE APPEND MODIFY 

permissions: READ 

In addition, if the file is created by the linker and is executable, then both the at¬ 
tribute and permission field will also have EXECUTE capability set. 

The access capabilities on a directory are quite different from those on files. Direc¬ 
tories are maintained by the operating system and a few specialized privileged 
commands. A user should never be allowed to write to a directory, and executing a 
directory is absurd. The following access capabilities exist for directories: 
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- You may open the directory for read. 

This allows you to discover the names of 
the files it contains. For example, the 
’Is’ command opens the iniicatei directory 
for read to list Its contents. 

- You may create new files under this directory. 

“ Y'011 may not pass through this directory when 
matching a pathname. 

- You may modify the attributes/permisslons of 
the directory. 

- This bit indicates that the file is a directory. 

It is controlled by the operating system and a 
few privileged commands. 

When a new directory is created it will by default have the attributes and permis¬ 
sions of: 

attributes: READ CREATE MODIFY DIRECTORY 

permissions: MEAD DIRECTORY 

The uses of these access capabilities are best explained by some examples. 

1. As a user you do not want other users creating new files under your directories. 
Once created they could remove write permission and you the owner of the 
directory could not remove them. You can stop this by ensuring that CREATE 
permission does not exist on your directories. This is the default. Shared direc¬ 
tories like Vtmp’ must be available for creating new files by all users and 
should therefore have CREATE permission. 

2. You do not want users to be able to access any of your files regardless of the 
permissions on the files. Simply ensure that BLOCK permission is set on the 
directory and users will be blocked from accessing all files (or sub-directories). 

3. You do not want users to see the names of your files. However, you do want 
one or two users or special commands to be able to access files they know the 
name of. Simply remove READ and BLOCK from the directory. Adding 
BLOCK would not only prevent users from seeing your files, but they could not 
even access them if they guessed their names. 

4. You wish all members of your group to be able to read and write a file you 
own. Simple add READ and WRITE group permission to the file. 

The capability of MODIFY is the most powerful since it allows you to change the 

other capabilities of the file. You must have MODIFY to use the CHATTR com- 


READ 


CREATE 

BLOCK 

MODIFY 


DIRECTOR! 
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mand on a file. Note that if you remove MODIFY from the attributes, then the file 

will be fixed for all time at its current capability set. For this reason the CHATTR 
command takes care never to remove MODIFY unless explicitly told to do so! 

8.8 User Numbers 

The owner of a file is indicated by a group number and a member number between 
0 and 255 inclusive. All members of group 255 are SUPER USERS and are 
privileged in the sense that they are not restricted by the permissions field of any 
file, only the attributes. They can therefore read/write/execute/append/modify other 
users files, regardless of the file’s permissions. Likewise, member 255 of each 
group is a GROUP LEADER and may access the files of all members in that group 
regardless of the permissions. All other users are constrained to access privileges 
determined by both the attribute and permission fields of any files they do not 
own. The owner of a file as well as its permissions are listed by the FILES com¬ 
mand with the +v (verbose) option. 

You will be assigned the group number of the super user if there is no password 
file. If a password file exists (see section ’Using QNX’) then you will be assigned 
a group and member number from that file when you login. 

In a multi-user system, all system directories should be owned by the super-user. 
This includes the directory "/user' 1 . However, each directory under "/user” should 
be owned by the user assigned to it. Since the super-user owns "/user", only he 
may create new user directories under it. To change the ownership, the g= and m= 
option of CHATTR should be used. For example 

mkdir /user/jsmith 

chattr /user/jsmith g=2 m=21 

will give ownership of directory /user/jsmith to user number 2.21. 

If you wish to restrict access of potentially dangerous commands, you should 
remove general execute and read permission from them. For example 

chattr p=-er /cmds/mount 

would prevent anyone but a super-user from executing the mount command, as¬ 
suming that /cmds/mount is owned by user 255.255. 

8.9 Device Names 

Until now a pathname has referred to devices which are capable of maintaining a 
directory structure, the most common being a disk drive. QNX also supports 
devices which contain no internal structure and communicate a character at a time. 
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These are referred to as character devices and consist of 

- terminals 

- line printers 

- modems and serial communication lines 


On the Personal Computer, the keyboard and display will normally act as your 
terminal. The display is not strictly a character device, but for convenience it is 
treated that way by the software. 

Some devices are read or write-only while other devices may be read from and 
written to. Your display is an output device and your keyboard is an input device. 
QNX pairs closely related devices like this and refers to them by a single name. To 
identify a character device you start your pathname with a dollar ’$’. The devices 
supported by QNX are 


$con - Your key boar d/display (console) 
$!pt - Your line printer 

$lpt2 - A second line printer 

SrndiTi - hirst serial port a) 

$terml - Second serial port (COM 2) 
$term2 - Third serial port 


$null - Returns end of file on input and throws 
characters away on output. 


These may also be referred to as $ttyO, $ttyl ... etc. There may be more or less 
devices configured depending on the version of QNX you have running on a par¬ 
ticular machine. The MOUNT command with no arguments will list those devices 
you have configured and are installed. 


mount 


QNX goes to some length to treat character devices and files as similarly as pos¬ 
sible. This is called device independent I/O. What this means is that any com¬ 
mand which expects to read or write to a device may also read or write to a file 
without modification. The reverse is also true. As an example the CP {copy) 
command is typically used to copy files. 

cp source Jile destination Jile 
Either or both pathnames may be a character device. 
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cp sourcejile $lpt . 

Anyplace where a pathname is acceptable, you may usually enter a device name. A 
device name is considered a subset of the class of pathnames. 



The QNX network links all machines together. Each node (machine) contains a 
file system which handles all file requests to disks attached to it. These requests 
may come from local tasks or remote tasks running on other nodes. The network 
extends the syntax for a pathname to include the node number on which the file or 
device exists. The node number is enclosed in square brackets and precedes the 
pathname. For example, the P command 

p 3 :/user/dtdodge/data 

would look on disk drive 3 on my node while 
p [4]3:/iiser/dtdodge/data 

would look on disk drive 3 of node 4. This represents a totally specified path¬ 
name. It should be noted that there are no artificial restrictions placed on the in- 
dicated drive. Drive 3 may be a floppy, hard disk or ramdisk. If a driver exists, it 
may be an optical disk or x.25 linking servicing the entire network. 

A missing node number will always default to your local node. 

g.10.1 Remote Search Order 

If the drive is omitted then 
p /user/dtdodge/data 

would use the search order on my node to search for the file on my drives. When a 
node is specified 

p [4]/user/dfdodge/data 

then the search order on node 4 is used and a search is made across it’s drives. 

Each node maintains two search orders, one for local requests and one for remote 
requests. 

search S 3 - search drive 5 then drive 3 

search 3 +remote - search drive 3 for remote access 
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Ill the above example, assume drive 3 is a hard disk and drive 5 is a ramdisk. The 
local users will search their ramdisk then their hard disk. A user on another node 
will only search the hard disk. 

8*10*2 Automatic Remote Searching 

You may specify a node in place of a drive to the SEARCH command. The com¬ 
mand 

search 5 [4] 

would search drive 5 (probably a ramdisk) then search on node 4 using its remote 
search order. This would be a typical search order for a node without it’s own hard 
disk. Node 4 would probably contain a hard disk and be thought of as a file ser¬ 
ver. It is possible for node 4 to also specify a node in its search command. 

search 3 [5] +reinote 

This would cause another indirection to node 5 and a search through its drives 

using its remote search order. If node 5 contains a node in it’s search order it is 
skipped. Only two levels of indirection are allowed. The second level allows a 
means of redirecting all file system requests to another node in one operation. 
Assume that node 1 was a file server and node 32 is a backup file server. The 
normal remote search order for node 1 might be 

search 3 +remote 

All requests could be referred to node 32 with the command 
search [32] +remote 

The following diagram illustrates a complex search across several nodes. 


NODE 1 



search 3 

[2] [3] 1 

- local search 

NODE 2 



search 2 

3 +remote 

- remote search 

NODE 3 



search 2 

[4] +remote 

- remote search 

NODE 4 



search 2 

+remote 

- remote search 
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An access to /path on node 1 would attempt to open the following files: 

3:/path 

[2]2:/path 

[2] 3:/path 

[3] 2:/path 

[4] 2:/path 
l:/path 


8.10.3 Remote Current Directory 

Your current directory may be on any drive on any node in the network. Simply 
precede the CD command with a node number 

cd [4]/user/dtdodge 

The PWD command will print out the pathname of your complete current direc¬ 
tory, indicating both the node and drive. 

pwd 


8.10.4 Mounting A Remote Disk 

There are a small subset of QNX commands and library routines which take a 
drive number as an argument. Their syntax does not allow for the specification of' 
a node number. To overcome this restriction the MOUNT command allows you to 
mount a virtual disk. The command 

mount remdisk 7 n=4 d=3 

will map all requests to disk 7 into node 4 disk 3. You may remap a virtual drive 
at any time. 

mount remdisk 7 n=4 d=3 
dcheck 7 

mount remdisk 7 n=6 d=l 
dcheck 7 

The concept of virtual disks is in fact the only means of remote access offered by 
most other networking systems. You might wish to consider it as an alternative to 
node numbers in your search command. The following will give you your own 
ramdisk and equivalence virtual drive 3 to the hardisk on node 1. 
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mount remdisk 3 n=l d=3 
mount ramdisk 5 s=64k 
search 5 3 


- remote hardisk 

- local ramdisk 


8.10.5 Network Devices 

A device name may be prefixed by a node number in the same manner as a path¬ 
name. 

cp file $lpt - local line printer 

cp file [4]$lpt - line printer on node 4 

8.10.6 Limiting Network Access 

Now that we have given you the syntax and mechanism for completely generalized 
access to any device in the system, it becomes necessary to restrict access. You 
may not wish to share your local ramdisk and floppy with another work station. 
Likewise, you may consider a dot matrix line printer connected to your computer 
as your exclusive property. The NACC command can be used to control every 
device attached to your machine. The default is NOT to grant access. You may 
enable READ and or WRITE permission as desired. For example 

nacc 2 $mdm +read +write - read and write for drive 2 

and $mdm 

nacc 3 +read - read access only for drive 3 

nacc CPU + write - allow remote task creates 

The last example allows other nodes to create and execute programs on your node. 
This very advanced feature separates QNX as a true fifth generation operating 
system. Please refer to the documentation on the NACC command for further 
information. 
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9. The Command Interpreter (Shell) 

The command interpreter, referred to as the "shell", acts as the interface between 
the user and QNX. To the shell, a command is a sequence of words separated by 
spaces. 

command argl arg2... argn 

The first word is treated as the name of an executable file (the command name) and 
all other words are considered as arguments to the command. Upper and lower 
case letters are different. If the command name begins with a slash then a search is 
made for the pathname exactly as specified, otherwise, the string "/cmds/" is 
prefixed to the pathname first. If after prefixing with "/cmds/" the pathname can 
not be found then the prefix is removed and a search is made under your current 
directory. For example, the command 

p data 

would cause a search for the executable file 
/cmds/p 

and only if that failed would it look for 

P 

under your current directory. 

This default search path may be changed by the PATH command which is 
described later in this chapter. 


The arguments are collected by the shell and passed to the command as strings. 

9.1 Shell Prompt 

The shell will prompt for input with a character followed by a space. The 
character prompt is different for the three classes of QNX users. 

$ - Super User 
# - Group Leader 
% - Regular User 
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The PROMPTT shell command may be used to precede the prompt with your tty 
number. This is useful on the console with multiple consoles. 

9.2 Command Input/Output Redirection 

When a command begins execution, it opens three files referred to as its standard 
input, standard output and standard error output. By default these all refer to your 
terminal. The shell is able to change these default assignments by recognizing the 
constructs: 


>pathname 
>*pathname 
»pathname 
»*pathname 
<pathname 


- redirect standard output to pathname 

- redirect error output to pathname 

- redirect and append standard output to pathname 

- redirect and append error output to pathname 

- redirect input from pathname 


As an example, the command "Is" ordinarily lists on your terminal the names of the 
files in your current directory. The command 

Is >my_files 

would redirect the output to the file "my_files". Likewise 

Is >$lpt 

would print them on the line printer. An interesting example of redirecting your 
standard input allows you to invoke the line editor with a script of editor com¬ 
mands. 


led file <scriptJile 

Although the redirection character and following pathname appear to be an argu¬ 
ment to the command, they are in fact interpreted completely by the shell and not 
passed to the command at all. Thus no special coding is required within the com¬ 
mand to handle input/output redirection. The redirection applies only to the com¬ 
mand executed and not subsequently executed commands. 

Programs which are started in the /config/sys.init.ftff files have their standard input 
set to $null. This means that programs which read data from standard input will 
get EOF. If you wish to start a task which can read from standard input you must 
redirect it. For example: 

rayprog < $ttyO 
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You can also use the ONTTY command: 

ontty $ttyO myprog 
ontty $tty5 my__ottier jprog 


C programmers may note that redirected HO pathnames are passed to their 

program as argvjargc] thru argv[argc + 2]. The current path is in argvfargc 
+ JJ. A value of zero indicates no redirection . 


9.3 Quoting 

Sinee arguments are separated by spaces it is not directly possible to pass spaces as 

arguments or a single argument containing a space to a command. To overcome 

this limitation the shell allows you to enclose in double quotes any argument which 
you want passed to a command as is. Some examples of quoting follow: 


cmd " " 
cmd " 15 

cmd ,f >file ,f 

cmd "abc def* ghi 


■ invoke command with one argument 
consisting of a space 

* invoke command with one argument 
consisting of a null string 

■ invoke command with one argument 
consisting of the string ">file" 

* invoke command with two arguments 
consisting of "abc def 1 and "ghi". 


In the third example the ’>’ is protected from the shell and cmd will not have its 
output redirected. In the fourth example the string "abc def with an embedded 
space is passed as one argument, not two. In all cases the double quotes are 
stopped off the argument before passing it to the command. 

There are cases where you may only wish to protect one character (perhaps a 
leading > or ’<’ on an argument) or the quote character itself. The shell under- 
stands the backslash character as a character which protects the character following 
it from the shell. The backslash character is NOT passed as part of the argument 
You may pass a backslash to a command by entering two of them side by side 
i he first simply protects the second. Therefore the cmd line 

cmd \"hello" \\ \>fil e 


QNX Shell 


QNX81 



would pass three arguments to cmd. 


"hello” 

\ 

>file 


A backslash does not lose it special significance when in double quotes. 

9.4 Filename Generation 


The shell treats the characters star (*) and question mark (?) special in the context 
of a filename. They are often referred to as global filename characters. A ? in a 
filename indicates that any character may occupy that position. A * in a filename 
indicates that zero or more characters may occupy that position. A search is made 
of all filenames in the current directory. Any files which match will replace the 
filename which contains the * and or ?. It is often convenient to think of the * and 
? forming a pattern which may match zero or more filenames. Since the pattern 
may be expanded into many filenames there is the possibility that you may over¬ 
flow the 512 byte maximum command line. If this happens you will get the mes¬ 
sage LINE TOO LONG. The following examples will illustrate a few simple 
expansions. 


type * 
type *.c 
type a* 
type *a* 
type *.? 
type p=* 


list all files in current directory 

list files which end in \c’ 

list files which start with an ’a’ 

list files which contain an ’a’ 

list files with a one character dot extension 

type the string ? p=*’ 


The last example illustrates that a filename will only be expanded if the characters 
around it are valid filename characters. The equals (=) is an invalid filename 
character, so no expansion was attempted. This check allows commands like WS, 
FILES etc to accept an argument of the form 


p -pattern 

without having to worry about the shell interpreting and expanding the pattern 
itself. Note that the shell can not handle an embedded * in a pathname. 

type /dir/* - not supported 

You should use extreme caution when using *. The innocent looking command 
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frel * 


will release ALL files at your current directory level! 

9.5 Querying 

When a command is followed by a question mark ’?’, it indicates that the com¬ 
mand should explain itself. 

In C programs, the command is informed by setting the number of arguments 
passed to it to zero. Each command normally receives at least one argument 
which is the command name itself 

All commands supplied by QNX have adopted this convention. The command 

Is ? 

will inform the LS command to print a terse usage message. This will often save 
you from pulling out your utilities manual when you are unsure of a command’s 
syntax. The ? should be the last character on a line. 

9.6 Background Tasks 

In QNX, the ampersand character is used to run commands in background 
(deferred). The task will be detached from your console and both the new com¬ 
mand and your command shell will run concurrently. The task-id of the new task 
will be displayed on your console (this can be disabled) followed by the $,# or % 
prompt from the shell indicating that you may continue to execute more com¬ 
mands. If you do not redirect the standard input for the new command it will be 
changed to the device $null, NOT your keyboard. The new task created will be 
immune from keyboard breaks. If you wish to explicitly kill it before it terminates, 
you may use the BREAK, KILL or SLAY command. For example 

slay dragon 

will kill the task with task name "dragon". If you are not the SUPER USER you 
may only kill tasks which you yourself have created. 

The priority of the new task may be decreased by following the with a minus 

sign. This is often used for programs you do not want to interfere with your 
keyboard response. This is especially true when you are in the full screen editor. 

. cc cprog &- 
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The LIST command is an excellent example of a command which can be run 
background to increase your productivity. Issuing more than one LIST command 
(from one or more terminals) will result in the requests being queued up waiting 
for the printer. The following would queue up 3 list requests. 


list cprog.c & 
list x=myfi!es & 
list *.c & 


In a network system or even a large single machine multi-user system you 
should consider using the spooler instead of direct calls to list. 


9.7 Multiple Commands On a Line 

You can place several commands on a line by separating them with a semicolon 
(;). For example. 

Is ; task 

If you wish to pass a real semicolon to a program you must quote it with double 
quotes or a backslash. 



The or-bar (I) character is used to set up pipes between commands. This connects 
the standard output of one command into the standard input of the next command. 
The effect of the command 

files | sort f=l 

is the same as 

files >file 
sort <file f=l 

The commands are connected by a pipe, implemented in QNX as a temporary file. 
The file used will be placed under the directory 7tmp\ When the shell dies it will 
remove any pipe files it may have created. You may change the names of the 
temporary files used with the ’defpipe’ command. For example, the command: 
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defpipe #$ 


will use a temporary file under the current directory with the name of the task 

number of the shell. A simpler example 

defpipe myjpipe 
will use temporary files 

mypipel and myjpipe2 

at the current directory level. Placing the temporary files on RAMDISK has the 
advantage of speed. 

Commands which are designed to read their standard input, transform the data in 
some way, then write to their standard output are often referred to as filters. You 
may connect several of these commands together via pipes in which each com¬ 
mand performs one operation on the data stream. 

9.9 Comment Lines 


Any input line to the shell which begins with a control character or a double quote 
will be ignored. These lines may be used for comments. 

9.10 Executing Commands on Another Node 

If a line is preceded with a node number in square brackets, the shell will attempt 
to run the following command on the indicated node. The default standard input, 

output and error will all be directed back to your terminal. The closing square 
bracket must be followed by a space to prevent confusion with a pathname. 


[4] task 

[4]task 

. [2] [4] task 

[2] cc [§]/dii7prog 

[1] list data 
[1] ontty 3 comm 

[1] ontty 3 dbadmin & 


Run the task command on node.4 
Load the task command from node 
4 and run it on this node 
Load the task command from node 
4 and run in on node 2 
Compile on node 2 the program 
Vdir/prog.c’ found on node 5. 

Rue the list command on node 1. 

Run comm on node 1 and have it 
attach to $tty3 on that node. 

Run dbadmin on node 1 in background. 
All messages will go to $tty3 on that 
node. No vc’s back to originating node. 
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[1] login 


- Create LOGIN on node 1. 


The last example would allow you to effectively login to node 1 as a virtual con¬ 
sole. All subsequently executed commands would now be run on node 1. Typing 
a Ctrl-d would log you off and return you back to the shell on your current node. 
You may only create tasks on other nodes if 

- You are the Network Super User (255.255) 0 
OR - That node has CPU write set using the NACC command. 

OR « The command is owned by the Super User and has 
been patched to have overriding remote create. 

Make sure you have NACC permission to write to your own console 
from the remote node! 

9.11 Command Files 

The command interpreter normally takes its input from the terminal. In the case of 
a command file it will take its input from a file containing QNX commands.. 

During the processing of a command file a question mark (?) at the start of a com¬ 
mand line will stop execution of the command file if that command returns a non¬ 
zero status. A command file can call other command files. 

9.11.1 Built-In Shell Variables 

The shell has a number of built in variables which may be referenced as #c where c 
is a single character. The #c sequence is replaced by a character string. If there is 
no #c replacement then then #c is replaced with the null string. All built-in shell 
variables with the exception of #u are expanded as numbers in the current base. If 
the base is 16 they are expanded as 4 hexadecimal digits and if the base is 10 they 
are expanded as a 5 digit unsigned number. The default base is 16. For example: 

Base 16 Base 10 

0000 00000 

000c 00012 

8000 32768 

You may turn the leading zeros on or off using 
the ” zeros on/off f command. 

The built in variables are: 

## - number of arguments 

#% - task number of shell 
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#$ 

#? 

#& 

#c 

#g 


#k 

#m 

#n 

#t 

#u 

#v 

#0 

#1 to 

#* 


#9 


- task id of shell 

- exit status of last command 

- task id of last background task 

- cyclic number which changes each second 

- group number of user 

- accept a line from the keyboard 

- member number of user 

- node number 

- tty number 

- userid of user 

- qnx version number 

- name of shell command 

- arguments passed to shell command 

- all arguments #1... #nn 


9.11.2 User Shell Variables 

The shell supports 10 integer and 10 string variables which may be read and 
modified by the user. Integer variables by default expand as numbers in the cur¬ 
rent base (same manner as built in variables) and string variables expand as text 
strings. You can force an integer variable to expand in any base by placing a Y or 
V in the name as follows. 


#i0 - expand iO using current base 

#it0 - expand iO using base 10 

#ix0 - expand iO using base 16 

You can perform arithmetic on the integer variables. They are modified using the 
SET VAR shell command and expanded using the following # notation: 

#i0 to #i9 - integer user variable 

#s0 to #s9 - string user variable 

For example, the following line would read a line of text from the terminal and 
save it in a string variable. 


setvar = sO #k 


Assignment and arithmetic is also straight forward. 


setvar = iO 123 

setvar = iO 0tl23 

setvar = iO 0x123 
setvar + il #i0 


set iO to 123 using current base 
set iO to 123 using base 10 
set iO to 123 using base 16 
add iO to il updating il 
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Please refer to the SET VAR command in the UTILITIES section of the manual 

under the SH utility. 

9.10 Executing Shell Commands 

Command files may be executed explicitly using the SH command 
sh cmdfile argl arg2... arg9 

or implicity by placing execute permission on the file and typing its name as a 
command. 

efiattr a=+e p=+e cmd_file - need only do this once 

cmd_file argl arg2... arg9 

The arguments argl, ...arg9 may be referenced as #1, ...#9 in the command file. 
For example a command file called rename, containing the line 

chattr n=#2 ffi 

would be invoked by either 

rename newname oldname 
OR 

sli /cmds/rename newname oldname 
The first example requires that the file have execute permission, 
chattr /cmds/rename a=+e p=+e 
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9.12 Local Shell Commands 

The shell examines each command entered and interprets a few special ones itself, 
rather than passing them off to the operating system to execute. These commands 
either modify the shell’s interface or are inconvenient to implement as regular 
system commands. Each command is described in the "Utilities" section of this 
manual. The following list summarizes each command’s function. 


back 

- suppress background tid 

base base 

- base for number expansions 

break taskjd 

- break a task 

cd [directory] 

-change directory 

debug [text] 

-debug a command 

defpipe path 

- pipe temp files 

ec shettjile 

-execute sh file 

else 

»conditional 

eudif 

-end a block if 

exit [status] 

- exit shell with status 

goto label 

-transfer control 

if test cmd 

- conditional 

kill taskjd ... 

- kill a task 

ontty tty cmd 

- create task on another tty 

passon 

- password protection 

path searckpath 

- change command search path 

pause 

- pause for carriage return 

pri [+\~]number 

»set priority 

prompt! 

- display tty number 

setvar op var val 

- set variable 

sharoff 

- don’t share code segments 

sharon 

- share code segments 

shift 

- shift # args down one 

stype [text]* 

»type arguments 

sysup 

- set system up flag 

then 

»conditional 

trap [label] 

- trap keyboard breaks 

type [text]* 

- type arguments 

verbose 

- toggle verbose mode 

zeros on/off 

- toggle verbose mode 
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9.13 Quick Reference to the Shell 

The syntax of a shell command line is 

[?] [!] [node] command argl arg2... 

The ? option will abort the shell on a bad exit status. The ! option will transform 
into the command instead of creating an extra shell for its execution. If you do this 
in a shell file, no commands beyond the one transformed into will be executed. 
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SHELL VARIABLES 

All number expansions are 4 digit 

leading zero hexadecimal by default 

## - number of arguments 

#? - last exit status 

#$ - shell task id 

#% - shell task number 

#& - last background task id 

#0-9 - argument 0 to 9 

#c - cyclic number 

#g - group number 

#k - take 1 line from keyboard 

#m - member number 

#n - node number 

#t - tty number 

#u - user name 

#v - qnx version number 

#* - ALL arguments 

#i0-9 - integer variable 

#s0-9 - string variable 


LABEL 

\name 

IO REDIRECTION 
< - standard input 

> - standard output 

» - standard output (append) 

>* - standard error 

»* - standard error (append) 

I - pipe (uses tmp files) 

; - cmd separator 

Leading TABS and SPACES are 
ignored and may be used for 
indentation 


USER COMMANDS 


base 

base 


break 

task id 


cd 

path 


debug 

[command] 


defpipe path 


ec 

command_file 


else 



endif 



exit 

[hex number] 


goto 

label 


if+f 

filename [cmd 

then] 

if+d 

dirname [cmd 

then] 

if+m 

filename [cmd 

then] 

if +a 

nodeid [cmd 

then] 

if eq 

str pat [cmd 

then] 

if ne 

str pat [cmd 

then] 

if It 

str str [cmd 

then] 

if ge 

str str [cmd 

then] 

kin 

task id 


ontty 

ttynum command 

passon 



path 

Ipathlpathl.... 


pause 



pri 

[+\-]number 


promptt 



setvar 

= var value 


setvar 

1 var value 


setvar 

+ var value 


setvar 

- var value 


setvar 

x var value 


setvar 

/ var value 


setvar 

% var value 


shift 



stype 

[text]* 


sysup 



type 

[text]* 


trap 

[label] 


verbose 
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10. Tasks 

This section is an overview of the concept of multi-tasking in the QNX operating 
'system. The discussion starts off very simply and progresses to the more complex 
issues and mechanisms within the operating system. 

10.1 Introduction 

It is by no means necessary to understand the underlying principles on which QNX 
is based in order to use QNX. For most users in a multi-user system, QNX will 
simply be an environment in which to run an application program on the same 
personal computer at the same time as someone else. How this is accomplished 
need not be known. However, a basic understanding is a definite asset. 

hi its simplest form, a task may be thought of as a program which accomplishes a 
particular task. In a multi-tasking operating system it is possible for several dif¬ 
ferent tasks (programs) to be executing (running) at the same time. The operating 
system accomplishes this by sharing the computer among the various tasks compe¬ 
ting for it. In a single tasking system the computer spends most of its time waiting 
on the user. At the speed at which most users enter characters, the computer could 
easily have read a thousand times that many characters. It is this speed that allows 
a multi-tasking system to appear to mn more than one program at once. In fact the 
system takes turns running the various programs. The rules governing which task 
to run and when are complex but can be summarized as follows. 

1. No task which is blocked (typically for input or output) will run. This means 
that a user program waiting for input will NOT compete with other tasks which 
are ready to run. 

2. No task is allowed to mn continuously for more than a fraction of a second (set 
by SLICE utility) if there is another task waiting. This prevents one task which 
is performing long complex calculations from locking all others out. Unlike 
point 1 above, the other tasks will be affected since they may now have to wait 
a fraction of a second for their turn to execute. In a multi-user system this is 
seen as a slight delay in response to commands. Should an appreciable number 
of tasks all consume their maximum time limit then response may suffer 
noticeably. In QNX, if eight users run a program which takes several seconds 
of dedicated processor time, then each program will appear to take eight times 
as long. Typically this does not occur because most tasks frequently request 
input/output. 

3. Tasks may be assigned priorities such that higher priority tasks will never relin¬ 
quish the processor to lower priority tasks. The time sharing of point 2 only 
applies to tasks at the same priority. 
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10.2 System Tasks 

When QNX is booted, five system tasks are created. These tasks run at a priority 
which is higher than any user created tasks. Each system task performs a well 
defined function as follows. 

TASK ADMINISTRATOR 

This task is responsible for creating and destroying tasks. It is also respons¬ 
ible for allocating memory for the tasks. This task runs at priority one, which is 
the highest task priority in the system. 

FILE SYSTEM ADMINISTRATOR 

This task is responsible for the file system. It handles all requests to open, 
close, read and write to files. This task runs at priority three. 

DEVICE ADMINISTRATOR 

This task is responsible for all character devices attached to the system. This 
includes your terminal, the line printer, etc. It handles all requests to open, close, 
read and write to devices. This task runs at priority two. 

IDLE ADMINISTRATOR 

This task simply consumes any spare processor time. Since this task runs at 
the lowest possible priority in the system (15), it only runs when QNX has nothing 
else to do. It therefore does not affect system performance. 

NETWORK ADMINISTRATOR 

This task is responsible for communication over the local area network. It 
handles all data requests which must be transmitted over the network. This task 
runs at priority 3. If you do not have a networking card installed, this task is not 
needed and will terminate itself. 

There are a other tasks which may be created after the system is running. Al¬ 
though not essential for the system to run, they provide valuable services. They 
are described below. 

TIMER ADMINISTRATOR 

This task is responsible for running a wakeup service. Any task can request 
to go to sleep for a specified period of time and this task will wake it up when that 
period elapses. It is also capable of signaling ports, setting exceptions and forcing 
a task ready. C programmers are referred to the file "/lib/timer.h M and the library 
routine settimerQ. The timer administrator may be started by typing (or placing 
in your "/config/sys.init" file) the command. 

timer & 
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SPOOLDEV ADMINISTRATOR 

This task creates virtual devices which spool information away to disk. This 
allows several people to use the device at the same time. When they close the 
device, the file is submitted to a real device in a first come first served order. 

LOCKER ADMINISTRATOR 

This task supports record locking and concurrent file sharing. The record 
locking is compatible with that found in Unix System V. 

QUEUE ADMINISTRATOR 

This task supports named queues which supplement QNX’s normal methods 
of intertask messaging. 

User tasks request services from these system tasks by sending messages to them. 
Upon sending a message the user task blocks waiting for the system task to receive 
the message, process it, then reply with some result. System tasks NEVER send to 
user tasks. The life of a system task can be summarized as follows. 

- Block awaiting a message. 

- When a message arrives, process the request and 
if the request can be satisfied reply indicating 
the result. 

- If the request can not be satisfied immediately, then 
remember it and wait for another message. 

When the request can be satisfied, often as the 
result of another received message, reply to the 
waiting task at that point. 

When running in a network, these messages may originate from other nodes on the 
network. The receiving task need not differentiate between local and remote mes¬ 
sages. 

10.3 Inter-task Communication 

QNX supports three types of inter-task communication. 

1. Messages 

send (tid, snd_msg, rep_msg, size) 
receive (tid, rcvjmsg, size) 
reply (tid, repjmsg, size) 
read_msg (tid, rcvjnsg, size) 
write_msg (tid, rep_msg, size) 
vc_create (nid, tid, size) 

2. Ports 
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attach (port) 
detach (port) 
signal (port) 
csignal (port) 

3, Exceptions 

set_exception (tid, sysexc, usr_exc) 

10.3.1 Messages 

A message consists of a sequence of data bytes from 0 to 65,535 bytes in length. 
Messages between nodes on a network are limited to the size of the virtual circuit 
buffer which was created for this communication. 

The contents of a message will usually fit a predefined structure agreed upon by 
both the sender of a message and the receiver. A receiving task may receive more 
than one type of message, with each message having a different structure. In this 
case the first byte of the message will usually indicate its type. Based upon this 
message type the receiver may then apply the proper structure for extracting the 
various fields within the message. The operating system does NOT check for 
consistency in message types between tasks. It considers a message to be a se¬ 
quence of data bytes and does not examine or assume any structure on the message 
itself. This view is consistent with that taken by the file system concerning the 
contents of files. The convention of using the first byte of the message to indicate 
message type may (or may not) be adopted by the communicating tasks themsel¬ 
ves. 

When a task SENDS a message to another task it will block until the receiving task 
RECEIVES the message and then REPLIES. When a task does a RECEIVE 
waiting for a message it will block until one is SENT to it. The operation of 
REPLY does not block. This presents two scenarios depending upon whether the 
send occurs before or after the receive. 
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TASK A 
A sends to B 


TASKS 


- A Mocked 

B RECEIVES from A 
. - B processes the message 
B REPLYS to A 

- A continues 

Diagram 10.1 


TASK A. 


A sends to B 
. - A blocked 

! B 

. - A continues 


TASKS 

B RECEIVES from A 

e - B Mocked 


. - B continues 

. - B processes the message 

REPLYS to A 


Diagram 10.2 


A physical transfer occurs at the point of the receive in Diagram 10.1 and at the 
point of the send in Diagram 10.2. This can be thought of as the synchronized 
connection point between the two tasks. Messages implement a totally syn¬ 
chronized communication. 

During the REPLY operation the receiver may also reply with 0 to 65,535 bytes of 
information back to the sender. The transfer occurs immediately and does not 
block since the sender is already blocked awaiting a reply. 

There are two types of receives, general and specific. A general receive may be 
satisfied by any sending task while a specific receive will only be satisfied by the 
one task indicated in the receive. All operating systems tasks perform general 
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receives since they do not. know beforehand the identity of .the user tasks sending 
to them; Sending to a task which does not exist or dies before replying will un¬ 
block the sending task. Likewise, performing a specific receive on a task which 
does not exist or dies before sending will unblock the receiver. 

Should more than one task send to the same receiving task, they will each block 
and. queue up on the receiving task. As the task performs RECEIVE operations it , 
will receive the messages in die time order that they were sent except in the case of 
a specific receive. In this case it will receive from that task only, regardless of de¬ 
position in die queue. 

Should two tasks send to each other at the same time, they will both block on each 
other resulting in a deadlock situation. This can be easily avoided by careful de¬ 
sign and by following these guide lines. 

L If possible, design your programs such that 
one task is a producer (sender) and the other 
a consumer (receiver). 

jU o jli iWU wtSiiCo IviLtJJL isvIlCt ILO cdlMtl Mllifcii., liikdJi&tl Mil 

a very rigid protocol stating when each may send 
and the other receive. A much better solution 
would be to create a third task which only performs 
receives, and have the other tasks send to it. 

The middle task would then reply appropriately 
to each task. This middle task is often referred 
to as an agent The QUEUE manager is an example of 
a generalized agent task. 

The queueing of sending tasks provides a mechanism for controlled, sequential 
access to a resource. Complex issues of synchronization, critical sections and 
semaphores are handled in a clear and uniform manner. For example, the classic 
problem of providing secure, controlled access to a database from multiple tasks 
(users) may be greatly simplified by placing a task between the files making up the 
database and the requesting tasks. The database administrator would now receive 
synchronized sequential requests to act upon the database. It would provide the 
intelligent interface to the file system. The file system need not contain complex 
record locking facilities. These are provided by the administrator task in a manner 
which is in harmony with the stmcture of the data. The task can also resolve ques¬ 
tions of access permissions, access statistics, access billing etc., a job which should 
not be performed by the file system or operating system. 

The following example is perhaps the most common occurrence in the QNX 
operating system. 
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1. User task A sends a message to the device administrator requesting a line of 
input. At this point task A is SEND blocked and will not compete for the 

processor. 

2. The device administrator receives the message from task A and starts to ran. 
Just before it received the message it would probably have been RECEIVE 

blocked awaiting a message. 

3. Task A goes from the SEND blocked state to a REPLY blocked state. It’s mes¬ 
sage has been received but it is still blocked awaiting a reply. 

4. The device administrator checks to see if there is a line waiting from the ter¬ 
minal indicated in the message. Lets assume that there is not. The device ad¬ 
ministrator will then remember task A’s request and again RECEIVE block 
waiting for another message. 

5. Sometime later, a user types carriage return on the terminal Task A has reque¬ 
sted a line from. The driver associated with that device sends a signal to the 
device administrator saying a line is available. 

6. The device administrator unblocks, and replies to task A with a message con¬ 
taining the line. It then RECEIVE blocks waiting for another message. 

7. Task A unblocks and starts running with a message containing the line. 

10.3.1a Death of a Task 

When a task dies (for any reason) it sends a message to each QNX administrator 
informing it of it’s death. This allows the administrator to clean up any resources 
allocated by the task before its death. Users who write their own system tasks may 
request that they also receive this message when tasks die. 

10.3.1b Messages Across the Network 

The QNX network extends the range of the message primitives across a local area 
network. It is this capability which truly separates QNX from other operating 
systems which claim local area network support. QNX integrates the local area 

network right into the heart of the operating system, at the fundamental level of 

inter-task communication. 

In the above example, TASK A sent a message to the device administrator to get a 

line of input from a device. There is no need for the two tasks to be on the same 
node. This means that a task on one node may communicate directly with any 
device on any node in the system. It just has to send to the appropriate device 
administrator task. This also applies to the file system administrator and the task 
administrator. 

To open a file, a user task sends an open message followed by read and write mes¬ 
sages to the file system task. The user task may therefore access any floppy, hard 
or ramdisk on any node by sending messages to the file system task on any node. 
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To create a new task, a user task sends a create message to the task administrator. 
By sending this message to the task administrator on another node you may ex¬ 
ecute remote task creations across the network. 

10.3.1c Virtual Circuits 

In these examples, the receiving task did not have to perform any special action to 
receive or reply to messages from remote tasks. It is the responsibility of the sen¬ 
ding task to set up the communication path to the receiver. This is accomplished 
by a QNX primitive which establishes a VIRTUAL CIRCUIT between the sending 
and receiving task. This primitive 

vid = vc_create(node_id, task_id, messagesize) 

returns the task-id of a virtual task which represents the task on the far node. 

There is a virtual task created at each node. You many now refer to the vid as 
though it were a local task, sending to it, receiving from it, etc... The operating 
system will ensure that all requests will be transparently sent over the network. 

The virtual circuit provides the necessary mapping between two tasks. It also en¬ 
sures that resources can be cleanly recovered across the network when a task dies. 
For example, assume that TASK A is a very nosy task and opened files on a large 
number of different nodes and being an irresponsible task, killed itself without 
closing any of its files. Upon the tasks death, the local task administrator would 
examine the virtual circuits set up by TASK A and send control messages to the 
destination nodes killing the virtual tasks at the other end. The death of these 
virtual tasks will be perceived as the death of TASK A to the remote tasks. They 
will then clean up in the same manner as the death of a local task, closing off 
TASK A’s files. Without the virtual circuit, the death of any task would have to be 
sent to every task on every node in the network just to be safe! This action would 
bring a local area network to it knees. 

If the poller is running and a node crashes, all nodes will be informed. They will 
check if any of their tasks have a virtual circuit setup to the crashed node. If they 
do, the local virtual task is killed and again the local tasks will perceive the death 
of the remote task on the crashed node. 

10.3.2 Ports 

Ports provide the important capabilities of 

- interrupt handler communications 

-simple non-blocking communication 

as well as the less important capabilities (due to names and messages) of 
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- identification of unrelated tasks on the same node 
* - semaphores 

10.3.2a Identification - single node only 

Knowing die identity of another task gives a task the ability to communicate with 
it. The task identities of the system tasks are fixed and thus known to all tasks. 
When a task creates a new task (son), both the father and the son are informed of 
each others task identities. In each of these cases the knowledge of identity enables 
communication by messages. The above message primitives do not satisfy the 
requirements of communication between unrelated tasks. 

A port is a globally known name to which a task may attach in order to com¬ 
municate with unknown tasks. QNX provides a minimum of 32 ports which are 
identified by number. The first 16 are reserved by the operating system of which 
the first eight are privileged. A task may attach, detach or obtain the identity of a 
task connected to a port. The following table summarizes die the action of die 
attach and detach primitives on a port. For each primitive the port may be free or 
already attached by another task. 

PORT IS FREE PORT ALREADY ATTACHED 

ATTACH return zero return task identity 

of attached task 

DETACH return zero return task identity 

of attached task 

Attaching to a free port claims the port, while detaching from an owned port frees 
it. Detaching from a port you do not own will return a value as above but it will 
not detach another task. It can therefore be used to obtain the identity of a task 
connected to a port. 

In the database example above, the database administrator would immediately 
attach to an agreed upon port. All tasks wishing to communicate with it would 
detach that port to obtain the task identity to which they must send. 

The use of ports for name serving is only suitable on a single machine. Under the 
network version of QNX the section on NAMES provides a better mechanism for 
' identification which will work on a single machine as well as a network. 
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The major purpose of ports is to allow interrupt handlers to communicate with 
tasks. The interrupt handler signals a port which a task as attached to. The signal 
will wake the task up allowing it to process the interrupt. 

10.3.2b Semaphores 

The operations of ATTACH and DETACH implement a semaphore which may be 
used to gain controlled access to a resource. QNX’s LIST command currently uses 
port 16 to gain access to the line printer. In a multi-tasking and multi-user system 
it is quite possible for several instances of the LIST command to be invoked con¬ 
currently. If they each wrote indiscriminately to the printer, you would end up 
with an intermixing of output. Instead, the LIST command attempts to attach to 
port 16 before opening the line printer for output. If successful, the LIST com¬ 
mand continues and starts outputting to the printer. If unsuccessful, then the 
printer is already in use by another task. In this case the LIST command sends a 
message to the LIST task which owns the port. Since LIST never does a receive, 
the sending LIST will block. When the attached LIST finishes and dies, it is de¬ 
tached from the port and all tasks send-blocked on it are unblocked. The sending 
LIST(s) will then again attempt to attach to the port. The code in LIST to imple¬ 
ment this consists of 2 lines of C code. 

These semaphores will only work on a single machine and not across a local area 
network. 

10.3.2c Signals 

A task may SIGNAL a port resulting in that port sending a message to the task 
attached to it. This form of communication is special in that 

1. The task performing the signal does not block. 

2. The message sent by the port contains no data. 

3. The signal may be performed by an interrupt 
handler. 

4. Messages sent by ports are queued ahead of 
regular messages and will be received first 
even if sent second. 

The first point permits a form of non-blocking communication. The task as¬ 
sociated with the port will receive the message when it does a RECEIVE operation 
from anyone or an AWAIT operation on a specific port. The task identity returned 
by the receive will be that of the port and is clearly distinguishable from any task 
identity. If a task sends multiple signals before they are received, they will all be 
remembered. The conditional signal (CSIGNAL) will not signal a port if there is 
already a pending signal. 
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The identity of the port which sent the signal is the only information which the 
attached task receives. It is not even aware of the task which performed the sig- . 
nal. This is much more limiting than the SEND primitive but adequately serves the 

purpose of informing the task that a particular event has occurred. For example, if 
a task was waiting upon the event of a game paddle switch being closed it could 
attach itself to a port and wait for a signal from that port. The signal would in¬ 
dicate the event. No extra data is necessary. 

Point three allows interrupt handlers to inform tasks of external hardware events. 
The game paddle example above would signal the event within the interrupt han¬ 
dler causing the task responsible for that piece of hardware to unblock and service 
it. The device administrator and file system administrator are both informed by 
signals when a line is available or a disk operation has completed. 

The final point simply gives communication by signals priority over that by mes¬ 
sages. When used in conjunction with signals from interrupt handlers, this gives 
hardware events priority over software requests from other tasks. 

10.3.3 Exceptions 

So far, all communication between tasks has been synchronous with the receiver. 
The receiver explicitly had to perform a receive operation and thus was expecting a 
communication. Exceptions on the other hand are asynchronous with the receiving 
task. They are usually generated by some abnormal event and may occur at any 
time during the task execution. The best example is the exception associated with 
a keyboard BREAK. When you run a program, you may type a keyboard BREAK 
(Ctrl Scroll Lock on PC keyboard) at any time. This has die effect of setting an 
exception on the task associated with the keyboard. There is NO way for the task 
to know if or when the exception will occur. If the task has not protected itself 
against this exception, then the default action is to kill the task. 

There are a total of 32 exceptions which you may set on the task. These corre¬ 
spond to bit positions within two 16 bit words. The operating system reserves the 
first 16 exceptions. User tasks may freely choose meanings for the second 16 
exceptions. Those currently defined by the operating system are 
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EXCEPTION HEXADECIMAL VALUE 
modem hangup 0001 

keyboard break 0002 

quit 0004 


communication error 0010 

missing shared library 0040 

floating point error 0080 

kill 0100 

memory violation 0400 

privileged 0800 

alarm clock 2000 

task termination 4000 

divide by zero 8000 


The ’kill’ and ’task term’ exceptions may not be protected against and always 

results in the task being killed. The ’task termination’ exception is the means by 
which a task terminates itself (normally or via an explicitly coded abort). 

Certain tasks, like the editor, do not want to be destroyed by exceptions like 
BREAK. Therefore, the operating system provides the ability for a task to either 
ignore exceptions or execute a user provided routine to handle them. In the case of 
the editor, it terminates the current operation and returns to command level. Note 
that due to the asynchronous nature of an exception it is necessary for the editor to 
protect itself by ignoring exceptions during certain critical operations. In these 
cases the exception is left pending until the editor re-allows it at which point the 
exception occurs. What the editor has done is to force synchronization of the ex¬ 
ception during these critical places. 

The capabilities of user tasks handling exceptions is best described using diagram 
10.3. For simplicity we will assume a single exception being set (one bit set in the 
exception word). 
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Diagram 10.3 


The exception fields of PERMIT, ALLOW, PENDING and FUNCTION are all 
maintained in the user task’s address space and may be manipulated directly. 

From within a C program they are referenced as 

extern unsigned Exc_permit[2], Exc_a!!ow[2]; 

extern unsigned Exc_pending[2] 5 Exc_bits[2]; 

The PERMIT field may be thought of as a bit mask against which an exception is 
applied. If an exception bit is set where a permit bit is not, then the task is not 
permitted to handle that exception and is killed (1). Once the exception makes it 
past this first mask, it is applied to the second mask called ALLOW (2). If this bit 
is clear then the task is not allowing this exception at this time and the exception 
bit is placed in the PENDING field (3). No other action occurs. The task may 
examine the pending field at any time in order to see if any permitted but disal¬ 
lowed exceptions have occurred. This allows the task to poll the bits at its con¬ 
venience. If all bits are disallowed then the bits can be treated as a 16 bit number 
which can be set by another task. Finally, if the bit in allow had been set, then the 
function whose address is in the FUNCTION() field would be invoked (4). In this 
case if there is not a function set up to handle the exception, the task is killed (5). 

It is possible for multiple exceptions to be set upon a task by setting more than one 
bit in the indicated exception. The above explanation operates on all 32 bits in 
parallel. Killing the task (no permit) followed by invoking the exception function 
(an allow) take precedence when considering multiple exceptions. The operating 
system tasks do not set multiple exceptions on a task. 
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The following table summarizes the actions for a single exception, permit and 
allow, bit path. 


PERMIT ALLOW 

ACTION 

clear 

clear 

kill task 

clear 

set 

kill task 

set 

clear 

set proper pending bit 

set 

set 

invoke exception function 


If a task sets an exception on a virtual task (vc_create), the operating system will 
forward the request to the node which contains the real task. The real task will 
have the exception placed upon it. 

A word of warning... If an allowed exception occurs, the task will become UN¬ 
BLOCKED before executing the exception function. This has the unfortunate side 
effect of causing errors if the program was waiting for input from the keyboard for 
example. User programs which handle exceptions should be prepared to handle 
errors at any point in their program. Please refer to the documentation on the C 
library routine EXC_HANDLER. 

10.4 Global Names 

As stated earlier, for a task to communicate, it needs to know the task id of the task 
it wishes to communicate with. QNX offers a mechanism where a task may attach 
a symbolic name of up to 8 characters which may be queried by other tasks. As¬ 
sociated with the name will be the node number and task id of the attaching task. 

A task may attach its name as local to a single machine or global across the entire 
network. 

The first type of attaching is handled by a table in the local task administrator. The 
second type is handled with the assistance of a server task which must be running 
on a node in the network. This is described in the technical note "Attaching and 
Locating Task Names" in the C binder. 

Attaching a name is similar to the attach and detach primitives on ports. 

10.5 Task States 

The previous sections have talked about tasks blocking. In QNX a task is always 
in one of six states. 

DEAD - . - Task does not exist or is 

being killed 

READY - Task is ready to run 

SEND BLOCKED - Task has done a SEND which 
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RECEIVEJBLOCHED 
REPLYJBLOCKED 
HELD 

NETWORK JBLOCKED 


has not been received 

Task has done a RECEIVE with 

no waiting send 

Task has done a SEND which has 
been received but not replied to 
Task is ready but has been 
explicitly held 

Task is blocked on a network 
request 


The three blocked states are all tied to the message communication primitives. The 
state of HELD indicates that the task is ready to run (not blocked) but is being 
prevented from running due to a HOLD operation on it. Performing a hold on a 
blocked task does not change its state. However, as soon as the task unblocks, its 
state will change to HELD, not READY. 

The highest priority task that is ready will be the task which is running. If there is 
more than one task ready at the highest priority level, then they will be time-sliced 
every fraction of a second. 

The possible state changes are indicated graphically in diagram 10.4. Hie arrows 
indicate’ a state- transition caused by the indicated reason. 



L Task seeds message 4. Task waits for message 

2. Target task receives message 5. Message received 

3. Target task replies 


Diagram 10.4 
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10.6 Task Ids 

A task id consists of a 16 bit word in which the lower 8 bits is a task number and 

the upper seven bits is a version number. Each time a task is created, it is assigned 
the task number of a dead task and the version number of that task is incremented 
by one. The version number ensures that a particular task number may be reused 
128 times before reusing a given task name. The telephone company follows a 
similar policy in not immediately re-using canceled numbers. By holding off on 
reassignment, there is less possibility of someone phoning the old number and 
getting an answer. Instead they get a number out of service. Similarly, in QNX, a 
send to an old task will usually fail. The top bit indicates whether the task is local 
or remote (virtual task). 

The task number must lie in the range of 1 to 254. The maximum number of tasks 
allowed and other system information may be obtained by using the TSK com¬ 
mand. 

tsk info 


Tne return values of system calls which return task names is summarized in the 
following table. 



MEANING 
Task does not exist 
Valid port name 
Valid task name 
System call failed 


where xx is any combination (00 to ff) and 
the top bit indicates if the task is 
0 - local (real) task 
1 - remote (virtual) task 


0500 - port five 

0508 - local task (number 8, 5th incarnation) 
8728 - virtual task (number 28, 7th incarnation) 


10.7 Task Hierarchy 

Tasks running in the system have a hierarchical (tree) structure which very closely 
parallels that of the file system. Each task has one father and zero or more sons 
and brothers. Two examples are shown in diagram 10.5. 
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doc playerl player2 player3 

Diagram 10.5 

When a task dies, all its children are also killed. This may seem harsh, but it is 
necessary to maintain a consistent task hierarchy. Imagine removing a directory 
without first removing the files under it! 

10.8 Task Creation 

When a task creates a son task, there are three major options available to it. 

1. It may wait upon the sons death before 
continuing to execute itself. 

2. It may continue executing in parallel 
with the son (concurrent). 

3. It may continue to execute in parallel 
with the new task but not preserve the 
father son relationship (background). 

As a result the death of the father 
task will NOT kill the new son task. 

The command interpreter (shell) by default always chooses option 1 unless you 
explicitly tell it to run the task background (option 3). Option 2 is not a common 
occurrence. One might imagine a large application program which consists of one 
father task which creates several son tasks, all performing a separate function, and 
running concurrently. Killing the father will remove (kill) all sons. 

In addition the father task may also set the priority of the son at creation. 

10.9 Terminal Ownership 

At any one time, only one task is associated with a terminal. This will be the most 
recent task to open the terminal for read. Besides receiving all input the task will 
also catch keyboard BREAKS. Each open stacks on top of the last open. Only the 
last open on the top of the stack is active. Closing a terminal will remove it from 
the stack. This may move a previous open to the top of the stack making it active 


QNX Tasks 


QNX109 



again. If a task which is not on top of the stack attempts to read from a terminal, 
the request will be queued until that tasks open becomes active. A remote task 
may take active control of the terminal by opening it in the same manner as a local 
task. This scheme has no ambiguity. 

When a task is created it may optionally be '’handed” down responsibility for hand¬ 
ling breaks on the device. It is possible for a son task to process data from a ter¬ 
minal, but have breaks still be set on the father task. 
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11. QUICS - The QNX Update System 

The QNX update system, called Quics, is a computer which runs 24 hours/day 
which you may call (using a modem) to: 

• Download fixes and changes to the operating system, utilities 

and libraries. 

• Download a variety of free software from various sources. 

• Send us electronic mail. 

• Engage in a conference with other QNX users on a large 
variety of topics. 

The first point allows us to provide you with a level of customer service which is 
second to none in this industry. For example, if you report a bug, perhaps in a 
utility or library routine, you can often download a revised version within hours of 
reporting the problem. We maintain on line, the most current versions of all 
programs including the operating system itself for download. Along with these we 
provide a list of all changes made to the system. You may wish to sign on once a 
month and make a log of this list. 

We also maintain a growing list of free software which may be of interest to you. 

It includes games, nifty utilities and a megabytes of source provided by ourselves 
and our customers. This source can be an invaluable aid in helping you to under¬ 
stand some of the intricacies of QNX. For example, the QUEUE manager shipped 
in binary form with your system is available in full source under the free software. 
The same is true for all disk and graphics drivers. 

If you are not in a hurry for an answer you can send us electronic mail which we 
will answer within a day or two. 

Lastly, if you would like to comment or ask a question which you feel other users 
may be interested in, then you will want to use our conference system. It has a 
command structure which is very similar to that used by Byte magazine’s con¬ 
ferencing system. All the QNX developers are members of the conferencing 
system as well as most of our more active developers. It is not unusual to pose a 
question and have several comments on it within an hour or so. There are topics 
on real time, hardware, utilities, c compiler,... and so on. You do not need to be a 
QNX customer to use the conferencing system. It can be accessed from a terminal 
or a terminal emulation program running under DOS. 

The machine you are calling is node 1 ofa large QNX network. ■ It is our boot node 
and the node from which most of our users get all their commands. While signed 
on, you are in fact sharing the machine with quite a few users. At the time of this 
printing the boot node is an 8 Mhz AT with 3 modem lines and an X.25 line into 
the Datapac public network which supports 4 (expandable to 32) additional users. 
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All three modems will support both 300 and 1200 baud service. We are always 
upgrading our equipment and some (if not all) of the modems will support 2400 
baud and we are looking to provide 9600 baud service as well. The 3 modems are 
on a hunt group with the primary number being. 

(613) 591-0934 • First number of the hunt group. 

An up to date configuration on the number of modems, their types and phone num¬ 
bers is maintained on the update system. You can read this when you give us a 

call. 

As stated above, we are also connected via an X.25 link to the Datapac public 
network. An X.25 card plugs into our AT and interfaces with X.25 software which 
mns under QNX. The X.25 link can support several user calls at one time. To 
connect with us via X.25 you will have to make a pre-paid call or register with us 
for an X.25 account number allowing you to make collect calls. Our network 
address is 

3020 85701416 

Our datapac address. 

L Datapac’s network code. 

11.1 How To Phone Us 

To call us you will have to use one of QNX’s terminal emulation programs. 

qtalk « A simple terminal program which comes with the system, 
qterrn ® A very slick, full featured terminal program which is 
separately purchased. 

Since QTALK is shipped with every system we will describe how to contact us 
using it. We will assume that your modem is connected to the QNX device 
$mdm. If it is not, you will have to specify to QTALK which tty device it is on. 


Step 1 Set your baud rate to conform to your modem as follows: 
stty baud=2400 par=none bits=8 >$mdm 

stty baud=1200 par-eene bits=8 >$mdm (QNX default at boot) 

stty baud=30O par=none bits=8 >$mdm 
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Step 2 Start QTALK and cause your modem to dial us. If you are in north 

america and have a hayes compatible modem you can use QTALKS’s 
dialing directory capability. We provide an entry with our phone number 
and the name "quics". Refer to the documentation on QTALK in the 
utilities section of the operating system manual for mote information. 

qtalk quics [m-modem__device] ® Hayes compatible modem,, 
qtalk [m~modem_device] © Other modem,, 

The option m -modemjievice is only necessary of your modem is not 
connected to the device $mdm. 

Step 3 When the word CONNECT is printed, wait one second. If you do not get 
a login message type the following 5 characters 

&b„caniagerretum 

L this is the <enter> key 

and repeat if necessary. You should get a screen of information telling 
you what to do next. One of your options will allow you to download an 
up-to-date manual on how to use Quics, the update system. 

11.2 X25 Access 

Quics is also connected to the Datapac packet network via an X.25 link. 

Customers may access the system by using a public dial-up port. Instead of 
placing a long distance phone call directly to one of QNX’s modem lines, you 
place a local call to a modem line on a packet network. Once connected to the 
packet network you will have to place a call to QNX’s X.25 link. This is accom¬ 
plished by entering a multi-digit number (referred to as a DNA, destination ne¬ 
twork address) to identify who you wish to call. Once a successful call is made, 
you will be connected to QNX’s update computer and all data will be routed 
through the packet network. Each country tends to have its own packet network 
with gateways connecting the many networks. Due to agreed upon standards, you 
should be able to access our update computer from nearly any country/network in 
the world. The standards, unfortunately, do not apply to the user interface pre¬ 
sented to the user when he wishes to place his call. At this point, you are com¬ 
municating with the network ( this is similar to the method by which you com¬ 
municate with a hayes modem when you wish to place a call) and each network has 
it’s own command language. Once die call has been established you are then 
communicating with QNX and the network should pass all data transparently. 

There are two major advantages of accessing the update system via X.25. 
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First, the networks communicate at very high speed and pass data to each other in a 
completely error-free manner. The only place a communication error is possible is 
between your modem and the network’s modem over the phone line on which you 
called. This will typically be a local phone call. Those of you who have tried to 
access the update computer directly using long distance may have discovered that 
the lines are often very noisy. It seems to depend on the time of day, phase of the 
moon and how badly you need the data. Our European customers have found the 
long distance line pretty much unusable. Our X.25 link has changed all this and 
for the first time we have a global update system. 

Second, access via the packet networks is often cheaper than the cost of a long 
distance phone call. This is especially true when you consider the re-transmission 
time caused by data errors. The cost is based upon both connection time and the 
amount of data transferred. Each network has it’s own rate schedule with some 
networks being more expensive than others. The different networks have agreed 
upon inter-network costs in much the same fashion as the international phone 
companies. 

You still have to use a QTALK or QTERM to contact us as: described above,, 

however, you will call your local public network and then use it’s commands to 
place a call to us. 

Contact QNX Software Systems Ltd’s marketing department for an application for 
an X.25 account which will allow you to place collect calls. 
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12. Tips on Using QNX 

This section consists of a few tips in getting started on QNX. 

12.1 Memory Requirements 

To boot QNX you need a minimum of 256K of memory. This can be expanded to 
640K in real mode and 15 Megabytes in protected mode. 

12.2 Enabling Colour 

You may change the colour of your text and screen by issuing escape sequences to 
your screen. As an example, the sequence 

Esc@71Esc!71 (Esc is the single Esc key) 

will set your character and fill attribute to white on blue. 

COLOUR CODES 


digit 

colour 

digit 

colour 

0 

black 

4 

red 

1 

blue 

5 

magenta 

2 

green 

6 

brown 

3 

cyan 

7 

white 


You should set your colour preference using ESC @ and ESC ! in your sysinit file 
and follow it with an ESC S to save it away. All QNX applications which play 
with the colour will print an ESC R to restore the saved colour before exiting. 

type Esc@l\Esc\l\EscS (Esc is the single Esc key) 

12.3 Disabling Colour 

If you have a colour card, but a black and white monitor, you may wish to suppress 
all colour since it makes text very hard to read. You can disable colour using the 
stty -f nocolour command. 

12.4 The Mount Command 

The MOUNT command allows you to dynamically reconfigure QNX. You may 

1. Install custom disk drives. 

2. Install consoles. 
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3. Install shared libraries. 

4. Install disk caches. 


By default QNX assumes a 360K (40 track) floppy disk drive for drive one and the 
same for drive two if it exists. On machines like the AT, QNX will automatically 
configure itself to support the 1.2M high capacity drives. On a PC, users may have 
an 80 track floppy for drive 2. To configure your 80 track drive, you would issue 
the command 

mount disk 2 t=80 n=9 h=2 


If you can spare the memory, a great improvement in hard disk access time can be 
made by installing a disk cache. For example, we could add a cache to disk 3 by 
issuing: 

mount cache d=3 s=32k 

If you are going to accessing large files in a random access mode (data bases), then 
a tremendous improvement in performance can be had by mounting an XCACHE. 
A file in QNX consists of one or more extents. Each extent is a contiguous series 
of blocks within the file. 

extent 1 extent 2 extent 3 


An XCACHE caches the information on how these extents are connected. This 
saves you from having to chain through extents when seeking within a file. Each 
extent connection requires 20 bytes. This cache is shared by all disks. 

mount xcache s=10k -enough for 512 extents 

Finally, you can speed up disk writes by mounting a bitmap cache. This cache 
takes up very little room and yet it can add significant performance when growing 
files. 

mount bmcache d=3 


Virtual consoles an extremely useful extension to QNX and can be added to the 
system (at the expense of another device entry which is hopefully not required) by 
a command such as: 
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mount console coni 

Shared libraries such as graphics libraries or floating point math libraries can be 

installed with commands such as: 

mount lib /drivers/glib.ega 
mount lib /config/qdb.slib 

The use of shared libraries allows application programs which run under QNX to 
be independent of hardware. 

12.5 Ramdisk 

One form of the mount command allows you to create a virtual disk in memory. 
This disk behaves exactly like a real disk in all respects except speed where it is 
much faster. To create a 200K ramdisk as drive five issue the command 

mount ramdisk 5 s=200k 


The ramdisk loads a driver into memory. As a result, the above command would 
require just a little bit more than 200K of memory to create the ram disk. You can 
only mount a single ramdisk. 

You must now initialize the disk using the dinit command as follows 

dinit 5 

QNX will not look on the ramdisk until you include it in its search order using the 
search command 

search 5 3 

hi this example we have indicated that we wish to always look on the ramdisk first, 
followed by drive 3. We will not look on drive 1 unless that drive number is ex¬ 
plicitly prefixed to the file name (1:/). 

Once the ramdisk has be initialized you may create directories and files on it. 
Creating the directory /Imp on it gives you a place to put all temporary files you 
wish to go away when you power off. The compiler places it’s temporary files 
under /tmp as well. 

mkdir 5:/tmp 
chattr 5:/tmp p=+c 
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Don’t forget to add general create permission on the /tmp directory if other users 
are going to be using temporary files. Ramdisks may be reinitialized by using 
DINIT and starting again! If you have sufficient memory, you may wish to create 
a larger ramdisk and place a /cmds directory on it. Copy down the editor and its 
macro file as well as any other commonly used commands. 

cp 3:/cmds/ed 5:/cmds/ed 
cp 3:/cmds/ed.macros 5:/cmds/ed.macros 
„ oe any other commonly used commands ... 

Ramdisk is also convenient for data logging over a high speed communication 
line. The pause going to a disk is eliminated. 

Once they get used to the speed, most users find it hard to work without a ram¬ 
disk! A ramdisk can be created from your sys.init.nn file. 

12.6 Shared Libraries 

Rather than duplicate code in many applications, or increase the size of the 
operating system, QNX has adopted the technique of dynamically mounting 
software libraries of code which can be shared. This technique can also be used 
provide machine independent interfaces to hardware. For example, a different 
Graphics library may be mounted for each type of graphics card. The user’s ap¬ 
plication program does not change. It makes calls into the shared library to ac¬ 
complish a function. The standard shared libraries are. 

/config/float.slib - software floating point 

/config/float8087.slib - 8087 floating point 

/drivers/glib.ega - Console/Graphics for ega card 

12.7 Operating On Groups Of Files 

QNX provides two very useful commands which allows you to execute a com¬ 
mand on a group of files. They are the EO (execute on) and WS (walk structure) 
commands. These routines may seem confusing to the novice, however, they will 
quickly become indispensible as you become familiar with the system. Please 
keep them in mind and refer to the documentation in the utilities manual. 
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Appendix A 

Character Set and Keyboard Codes 


QNXTips 


QNX119 

























ASCII Code to ASCII Character Table 


Upper 4 bits 


01 2 3 4 5 6 7 



DLE 

SP 

o 

@ 

P 

% 

P 

SOH 

DC1 

1 

i 

A 

Q 

a 

q 

STX 

DC2 

m 

2 

B 

R 

b 

' r 

ETX 

DCS 

# 

3 



c ■ 

s 

EOT 

DC4 

m 

4 . 

D - 

WM 

d 

t 

ENQ 

NAK 

m 

5 



e 

u 

ACK 

SYN 

& 

6 

F 

■ 

£ 

V 

BEL 

ETB 

§ 

7 

G 

w 

g 

w 



m 

8 



h 

X 

HT 

EM 

) 

9 

M 

Y 

M 

y 

LF 

SUB 

m 


m 


j 

z 



+ 


m 

c 

k 

{ 

FF 

FS 


m 

L 

\ 

1 

I 

CR 

GS 


m 

M 

] 



SO 

RS 


> 

N 

A 

n 


SI 

US 


m 



o 

DEL 


CONTROL CODES 


NUL - Ctrl § 
SOH - Ctrl a 

STX. - Ctrl b 

ETX - Ctrl e 
EOT - Ctrl d 
ENQ - Ctrl e 
ACK - Ctrl f 
BEL - Ctrl g 


BS - Ctrl h 

HT - TIB 
LF - Ctrl j 
VT - Ctrl k 
FF - Ctrl 1 
CR - Enter 

50 - Ctrl n 

51 - Ctrl o 


OLE - Ctrl p 
DC1 - Ctrl q 
DC2 - Ctrl r 
DCS - Ctrl s 
DC4 - Ctrl t 
MftK - Ctrl u 
SYN - Ctrl v 
ETB - Ctrl w 


CAN - Ctrl x 
EM - Ctrl y 
SOB - Ctrl z 
ESC - ESC 
FS - Ctrl | 
GS - -Ctrl ] 
BS - Ctrl A 
US - Ctrl 






















































QNX Keyboard Codes 


Upper 4 bits 



8 

9 

A 

B 

C 

D 

E 

F 


Shift 

Shift 


Ctrl 

Alt 



Alt 

0 

TAB 

F6 

Home 

Home 

Boom 



P 



Shift 


Ctrl 

Alt 

Alt 

Alt 

Alt 

1 

FI 

F7 

up 

up 

up 

FI 

a 

q 



Shift 

ph 

Ctrl 

Alt 

Alt 

Alt 

Alt 

2 

F2 

F8 


Fgup 

PgUp 

F2 

b 

r 



Shift 


Ctrl 

Alt 

Alt 

Alt 

Alt 

3 

F3 

F9 

minus 

minus 

minus 

F3 

C , 

S 



Shift 


Ctrl 

Alt 

Alt 

Alt 

Alt 

4 

F4 

F10 

left 

left 

left 

F4 

d 

t 



Ctrl 


Ctrl 

Alt 

Alt 

Alt 

Alt 

5 

F5 

FI 

five 

five 

five 

F5 

e 

u 



Ctrl 


Ctrl 

Alt 

Alt 

Alt 

Alt 

6 

F6 

F2 

right 

right 

right 

F6 

f 

V 



Ctrl 


Ctrl 

Alt 

Alt 

Alt 

Alt 

7 

F7 

F3 

plus 

plus 

plus 

F7 

g 

w 



Ctrl 


Ctrl 

Alt 

Alt 

Alt 

Alt 

3 

F8 

F4 

End 

End 

End 

F8 

h 

. X 



Ctrl 


Ctrl ' 

Alt 

Alt 

Alt 

Alt 

9 

F9 

F5 

down 

down 

down 

F9 

i 

y 



Ctrl 


Ctrl 

Alt 



Alt 

A 

F10 

F6 

PgDn 

PgDn 

PgDn 



z 


Shift 

Ctrl 


Ctrl 

Alt 




B 

FI 

F7 

Ins 

Ins 

Ins 





Shift 

Ctrl 


Ctrl 

Alt 

Shift 

1 

Alt 


C 

F2 

F8 

Del 

Del 

Del 

F12 

1 



Shift 

Ctrl 


Ctrl 

Alt 


Alt 


D 

F3 

F9 

PrtSc ' 

PrtSc 

PrtSc 


& 



Shift 

Ctrl 


Ctrl 

Alt 


Alt 


E 

F4 

F10 

Fll 

Fll 

Fll 


n 



Shift 

Ctrl 


Ctrl 

Alt 


Alt 


F 

F5 

TAB 

F12 

F12 

F12 * 


O 



Note: 

The above codes are preceded by a hex FF code, if the option EXPANDJFUNC is turned on, and the indicated 

function keys are pressed. 

The above codes can also be generated as a compose character, which results when the ALT key is pressed and 
released, then 2 more characters are typed, compose characters are NEVER preceded with an FF code. 















































































































Alt C 
Alt u 

Alt e 
Alt a 
Alt a 
Alt a 
Alt a 
Alt c 
Alt e 
Alt e 
Alt e 
Alt 1 
Alt 1 
Alt i 
Alt A 
Alt A 

Alt * 
Alt + 
Alt > 
Alt < 
Alt - 
Alt ~ 
Alt o 
Alt . 
Alt s 
Alt g 
Alt * 




Alt 

E ' 

E 

Alt 

a 

* 

a 

Alt 







✓ 


Alt 

A e 

ae 

Alt 

i 

' 

i 

Alt 

Alt 

A E 

JE 

Alt 

0 


o 

Alt 

Alt 

o * 

A 

0 

Alt 

u 


/ 

u 

Alt 









Alt 

o " 

• • 

0 

Alt 

n 

- 

n 

-•w 

Alt 

Alt 

o ' 

0 

Alt 

N 

- 

N 

Alt 

Alt 

u * 

A 

u 

Alt 

a 


a 

Alt 

Alt 

u ' 

u 

Alt 

o 


0 

Alt 

Alt 

y " 

y 

Alt 

? 

? 

# 

6 

Alt 

Alt 

0 " 

• m 

O 

Alt 

+ 


r~ 

Alt 

Alt 

u M 

• m 

u 

Alt 


-f 

i 

Alt 

Alt 

c | 

c 

Alt 

/ 

2 

14 

Alt 

Alt 

L - 

c£ 

Alt 

/ 

4 

J /4 

Alt 

Alt 

Y - 

¥ 

Alt 

j 

1 

i 

Alt 

Alt 

P t 

R 

Alt 

< 

< 

« 

Alt 

Alt 

f - 

f 

Alt 

> 

> 

» 

Alt 


a OC 

* r 

j 77 

e Z 
s O’ 

u y 

t T 
I § 

- e 
w n 

* S 

oo 

o 

/ <t> 

u n 


Release Alt before typing 2 character 
Input sequences 





AT disk 10 

Alive 33 

Argv 81 
Attach 101 
Attributes 69 
BIOS disk 11 
Background 83,109 
Backslash 81 
Backup 17 
Bad blocks 16,17 
Baud rate 38 
Bios driver 19 
Bitmap 62 
Blocking 93 
Bmcache 21 
Booting 

Sys.init 20 
floppy 3 
hard disk 18,20 
network 31 
COM1 37 
Cache 21,116 
Carrier detect 43 
Cd 67 

Change directory 89 
Characters, foreign 45,48 
Chattr 73 
Colour 115 
Comm 41,43 
Command files 86 
Command interpreter 79 
Communication 95 
Compose characters 45,48 
Concurrent 109 
Conference system 111 
Configuration, os 27 
Consoles 

colour 115 
graphics 58 
memory 55 

mounting extra ones 55 

Ctrl-z 48 

Current directory 67,77,89 

DCE/DTE 39 

Datapac 112 


Date 3 
Dcheck 17 
Death 99,100,109 

Detach 101 
Device 
editing 41 

escape sequences 50 
input 45 
input gate 49 
line editing 46 
line recall 49 
output 50 
smartcards 44 
type-ahead 46 
Device admin 94 
Device names 73,74,78 
Devices 45 
Dinit 16 
Directories 
moving up 68 
Directory 62 
changing 67 
current 67 
number files 62 
printing 68 
structure 62 
Disks 7 
at 10 
bios 11 

booting 3,18,20 
booting from 18 
cache 21 
controller 7 
drivers 7 
formating 15 
hdiskxfg 19 
installation 12 
mounting 8,14 
nighthawk 11 
partition 12,14 
ps/2 11 

second physical 27 
xt 9 

. Dmark 16 
Dos partition 13,26 
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Download 111 

Drive numbers 66 

EGA 

smart cards crashing 57 
switching consoles 57 
Ega117 

Exceptions 95, 103 
actions 106 
catching 104, 105 
list of 103 
network 106 
Execute permission 88 
Fdformat 15 
Fdisk 14, 20 
File admin 94 
File system 
attributes 69 
bitmap 62 
commands 65 
current directory 67,77 
device names 73 
directories 62 
drive numbers 66 
file names 61 
max file size 61 
network 75 
network access 78 
node numbers 75 
pathnames 65 
permissions 69, 73 
ramdisk 117 
remdisks 77 
search order 66, 75 
structure 61 
text files 41, 61 
user numbers 73 
Flashing text 51 
Flow control 41 
Foreign characters 45, 48 
Free software 111 
Graphics 

Libraries 58 
consoles 58 
Group 73 

Group permissions 69 


Hard disks 
see Disks 7 
Hdisk.cfg 19 
Hierarchical 62 
Highlighted text 51 
Input 45 
Installation 
command 5 
manual 7 
network 29 
summary 22, 32 
Inter-task communication 95 
Interrupt handlers 103 
Inverse text 51 
Keyboard 
input gate 49 
line editing 46 
line recall 49 
shift keys 45 
type-ahead 46 
Kill_vcs 33 
Line editing 46 
Line recalling 49 
Locker admin 95 
Login 3, 42 
modem 42 
Macros 86 
Member 73 
Memory 

Requirements 115 
Used by consoles 55 
Message deadlock 98 
Message example 98 
Message queuing 98 
Messages 95, 96, 99, 100 
Mkdir 73 
Modem 42 
Modems 37, 41 
Mount 115 
consoles 55 
Multi-tasking 93 
Multi-user 93 
Nacc 30, 78 
Names 106 
Netboot 31 
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Netboot directory 18 
Network 94 

access 30,78 
booting 31 
diagnostic tips 35 
exceptions 106 
hardware 29 
installation 29 
installation summary 32 
messages 99 
poller 32,100 
Network admin 94 
Nighthawk disk 11 
Node numbers 30, 75 
Nodes 85 
Non-blocking 102 
Null modem 39 
Or-bar 84 
Osconfig 27 
Other permissions 69 
PS/2 disk 11 
Parallel 43 
Parity 38 
Partition 5,12, 14 
dos 26 

more than one 26 
Passwords 31,73 
Pathnames 65 

absolute 65,66,67 
network 75,78 
relative 67 
Patterns 82 
Permissions 69, 73 
access chart 69 
default 71,72 
examples 72 
types of 70,71 
Phone numbers 1,112 
Pipes 84 
Poller 32,100 
Port 

ids 108 

Ports 95,100 

identification 101 
interrupt handlers 101,103 


semaphores 102 
signals 102 
Printer 41 
Printers 37, 43 
Priority 83, 89, 93 
Pwd 68 

QNX loader 18 
QNX partition 12,14 
QUICS 111 
Qtalk 43, 112 
Qterm 43 
Queue admin 95 
Quics 111 
phone numbers 112 
x.25 113 
RS-232C 
see serial 37 
Ramdisk 117 
Rebooting 48 
Receive 96 
Record locking 95 
Record separator 61 
Redirection of I/O 80 
Remote Disks 77 
Remote execution 85 
Remote search 75 
Reply 96 
Root 62, 65 
Scheduling 93 
Screen 

colour 51, 52, 53 
cursor addressing 51 
escape sequences 50 
Search 17 
remote 30 

Search order 65,66,76 
example 76 
indirect 76 
remote 75 
Semaphores 102 
Send 96 
Serial 37 
4/8 port cards 38 
baud rate, parity 38 
cables 39,40 
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coml, com2 38 
flow control 41 
i/o ports 37 
interrupts 37, 38 
login 42 
modem 42 
modems 41 
outgoing calls 43 
printer 41 
problems 43 
ps/2 38 
smartcards 44 
Server 98 
Setvar 87 

Shared libraries 118 
Shell 79 

Variables 86, 87 
background tasks 83 
command files 86, 88 

OQ 

uuimiiailuS Cty 

comment lines 85 
multiple commands 84 
pipes 84 
prompt 79 
quoting 81 
redirection 80 
reference chart 90 
remote execution 85 
sys.init 80 
useage message 83 
variables 86 
wildcards 82 
Signals 102 
Smartcards 44 
Spooldev admin 94 
Standard I/O 80 
Star 82 
States 106 
Stty 38 

Super user 4,73, 83 
Sys.cfg 27 
Sys.init 30 

Standard I/O 80 
sample contents 20 
System tasks 94 


Sytem initialization file 30 
Task 

. background 83 

code sharing 89 
communication 95 
creation 48,109 

death 99,100,109 
exceptions 95, 103,104 

hierarchy 108 
ids 108 

messages 95,96,97,98,99 

names 106 

ports 95,100,102 
priority 83, 89, 93 

scheduling 93 

states 106,107 

system 94,95 

tty 109 

virtual circuits 100 
Task admin 94 
Technical support 1 
Terminals 109 
Text files 41,61 
Time slice 93 
Timer admin 94 
Tips 115 
Tree structure 62 
Underline text 51 
Update system 111 
Usage message 83 
User directory 62,73 
User numbers 73 
Variables 86, 87 
Vc_ereate 100 
Virtual circuits 100 
Warm boot 48 
Wildcard 82 
X.25 111, 113 
address 112 
phone numbers 111 
XON/XOFF41 
XT disk 9 
Xcache 21 


Index 


Index 












QNX Utilities 


QNX is provided with a variety of utilities which aid in the management of files, 
the creating and formatting of diskettes, communicating with other computers, etc. 

The following pages describe the standard QNX utilities and how to use them. 
Each utility will be described separately, starting with a brief description of the 
command syntax, followed by a list of all possible options and a few examples. 
The command will then be described in more detail. References to other similar or 
related utilities may be included. 

In the following pages, the syntax of a utility may include a few of the following 
characters: 

[.„] - Square brackets are used to indicate OPTIONAL 

fields or arguments. 

| - OR bar is used between ALTERNATIVES, one of which 

must be selected. 

* - Asterisk following an argument indicates that a 

REPETITION of that field is also allowed. 

Any arguments which contain boldfaced characters may be abbreviated to the 
boldfaced characters alone. 

Italics are used to represent data which the user must supply, such as a filename or 

number, 

A few examples are included with every utility to help make the syntax of that 
command more obvious. 
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Command Summary 


QNX is shipped with a rich variety of commands. It is well worth the time to look 
through all of this section, reading enough about each utility to get a good feel for 
what it does and when you would use it. This way, you will know what to look for 
later, when you need to refer to the manual for the precise details on a particular 
utility. 

Learning the commands available on an operating system is one of the first tasks 
which confronts most new users. Depending upon your level of experience, this 
can be a slow process. To aid you in this respect we have listed most commands 
by category. The most frequently used and needed commands are marked with a 


star (*). 


Communicate 

COMM 

m 

- Modem communication handler 

QCP 

- QNX Communications Protocol 

QTALK 

* - Talk over Communications Line 

STTY 

* - Set TTY options 
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C mm mmti m 

COMM 

QCP 

QTALK 

STTY 


- Modem communication handler 

- QNX Communications Protocol 

* - Talk over Communications Line 

* - Set TTY options 


Configuration Utilities 

ACCOUNTANT 

BOOT 

CLOCK 

CLRHOUSE 

CRON 

DATE 

DEFJ5ERVER 

DEFPIPE 

FDISK 

KBD 

LOCKER 

MOUNT * - 

ONTTY 

OSCONFIG 

PASSON 

QUEUE 

RTC 

SEARCH 

SHARON/SHAROFF - 

SLICE 

TCAP 

TIMER 

TSET 

TZSET 


Accounting Task 

Select an OS file for disk booting 

Display Time and Date On Console 

A distributed database and name server 

Schedule commands in background 

Display or set date and time 

Define id of global name server 

Define temp files for pipes 

Create QNX disk partition 

Redefine keyboard layout 

Implement record locking in QNX 

Mount disk drives, consoles or libraries 

Create task on another tty 

Change operating system parameters 

Turn on password protection 

Implement queued message passing in QNX 

Get Date from Real-time Clock 

Define or Query the Disk Search Order 

Do/don’t share code segments 

Set the timeslice rate 

Manage terminal capability database 

Implement timing facility in QNX 

Set terminal type 

Display or set timezone offset 


Development Utilities 
CC 

DEBUG 

LINK 

MAKE 


Compile Command (C, Basic,...) 
Invoke the low level system debugger 
Link object files 
Maintain and recreate files 



CfckMMlJfis 

CHKFSYS 

DCHECK 

DCOPY 

DDUMP 

DINIT 

DMARK 

FDFORMAT 

PARK 

QUERY 


- Check entire file system for consistency 

- Check a disk for bad blocks 

- Copy entire disk to a second disk 

- Dump the contents of a disk block 

- Disk Initialization 

- Mark bad tracks on a disk 

* - Format floppy diskettes 

- Park the heads of a hard disk 

* - Query the utilization of a disk 


Editing and Word Processing 
ED * - Full screen editor 

LED - Line Editor 


CD 

CHATTR 

CHGRP 

CHMOD 

CHOWN 

OREL 

EO 

FREL 

MKDIR 

PWD 

RM 

RMDIR 

WS 

ZAP 


* - Change current Directory 

- Change Attributes of a file 

- Change group (group number) of a file 

- Change mode of a file 

- Change owner (member number) of a file 

- Release Directory 

- Execute On a list of files 

* - Release File 

* - Make directory 

- Print Working Directory 

* - Remove files 

- Remove directories 

* - Walk directory Structure executing a command 

- Zap damaged files out of existence 


BAR 

DUMP JOB M 


Draw Bar Charts 

Make a hardcopy of Graphics Screen 
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Information Handling 

CRYPT 

- Encrypt/Decrypt files 

DIFF 

- Difference between two files 

DUMP 

- Dump the contents of a file in hexadecimal format 

EXPL 

- Explain 

GREP 

- Search a file for a pattern 

LOCATE 

* - Locate patterns of characters in a file 

MORE 

* - Display a file or stdin by pages 

MSORT 

- Merge sort utility 

PACK 

- Pack a file to reduce its size 

PATCH 

- Patch files 

SIZE 

- Display the size of a file 

SORT 

- Sort files 

SPATCH 

- Full screen patch utility 

UNPACK 

- Unpack a packed file 

wc 

- Word count 

XLAT 

- Translate Characters 

I.istinp DirM'fnries and Fil PS 

DIR 

* - Display directory tree 

FILES 

* - List Files 

FSTAT 

- Display file status 

LS 

* - List directory 

MisMlanfigus User Commands 

APB 

- Send a Public Bulletin 

BEEP 

- Beep a user on another terminal/machine 

BREAK 

* - Break a task 

CALC 

- A simple calculator 

EC 

- Execute a shell file 

ECHO 

- Echo arguments to standard output 

KILL 

* - Kill a task 

LOGIN 

* - Log-in to QNX 

LOGOFF 

* - Terminate a QNX Session 

PATH 

- Change command search path 

PRI 

- Set priority 

PROMPT! 

- Display tty number 

PRTSC 

- Print Screen 

SH 

* - Execute Shell Commands 

SLAY 

* - Kill a task by name 

SLEEP 

- Sleep for a number of seconds 

STYPE 

- Type arguments on the terminal (no CR/LF) 

TYPE 

- Type arguments 



MffldngJiMs 

BACKUP 

CAT 

COPY 

CP 

FBACKUP 

MV 

SPLIT 

TBACKUP 


* - Backup Files to a backup diskette 

- Concatenate input files into one larger file 

* - Copy files 

* - Copy files 

- Archive files to floppy disk(s) 

* - Move files 

- Split a file into one or more files 

- Archive files to QIC60 tape(s) 


Network QNX Utilities 

ALIVE 

KILLJVCS 

NACC 

NET 

NETBOOT 

NETSTATS 

NETTEST 

POLL 


Set up/down status of a node 

Kill all virtual circuits to a node 

Set network access to disks, devices and CPU 

Query machines on the network 

Service boot requests from the network 

Display network statistics 

Check data transmission between two nodes 

Poll nodes (network version only) 


Printing Utilities 
LIST 

LPS 

P 

SPOOL 

SPOOLDEV 


List files on the line printer 
Postscript Laser Printer Filter 

Print file contents on terminal 
Spool files to a printer 
Create Pseudo-Printers 


System Information 

ACCSTATS 

DOPEN 

FOPEN 

SAC 

TSK 

WHO 


Print Accounting Statistics 
Display open devices 
Display open files 

Display system activity at each priority level 
Display task information 
Who is logged-in to the system 


6 




ACCOUNTANT -Accounting Task 

Syntax: 


accountant [b=bufjimit] [ f=file_namel ] [f-filejiame2] [t-ttys] 

[^verbose] & 

Options: 

b-bufjimit - Number of accounting entries to buffer before switching 
to secondary file (if it was specified). 
t-filejiamel - Primary file to save accounting entries in. 
i=filejiame2 - Secondary file to save accounting entries in. 
i=ttys - List of tty’s to gather accounting information on. 

+'verbose - Print each loginAogoff on the screen. 

where: ttys = ttyj'ange[,ttyjrange\ 

ttyjange = ttyjtum[:tty_num] 

Examples: 

accountant & 
accountant t=0,2,3:6 & 
accountant f=3 :/accounting/log & 
accountant f=3 :/accounting/logX & 

accountant f=3 :/accounting/logX f=[4]3 :/accounting/logX b=50 & 

Description: 

ACCOUNTANT is a task which runs in background and collects accounting 
information from the QNX TASK administrator. In a local area network you must 
run ACCOUNTANT on each node for which you wish to collect accounting 
information. If you do not specify which tty’s to gather information on, then 
information will be gathered on all tty’s. 

Accounting information is generated on each login and logoff of a user. Each 
accounting entry is 48 bytes long and contains the following information. 

struct accstat__entry { 

char accsjype; /* O-Not Used 1-Login 2-Logoff >3-User defined */ 
char accstty; 
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ACCOUNTANT 


unsigned accsnid; 
char accsgroupnum; 
char accsjiserjnum; 

unsigned accs_tlme[2]; 
char accs_name[16]; 
char accs_spare[48-16-4-6]; 

}; 


This program may be run in one of two modes, file mode or buffered mode (the 
default). 

FILE MODE 

When you specify the name of a file using the f-filename option, accounting 
information is immediately written to the file. If the filename ends in a capital X, 
the X will be replaced by the year and month (eg: 8701 for January 1987). For 
each record written the file is opened and closed. If the file is busy, 
ACCOUNTANT will retry the open 10 times. If that fails it will buffer the 
information in memory. This procedure is followed for each accounting entry 
received. When the file is successfully opened, all buffered accounting entries will 
be written. There is room for about 1000 buffered entries, after which any new 
ones will be lost. 

If you have specified a secondary filename, ACCOUNTANT will switch over and 
attempt to use it, after buffering a certain number of accounting entries. This limit 
defaults to 100 but may be changed using the b -buffer Jimit option. If you specify 
two files, any program which prints reports will have to read from both files 
removing accounting information in time order. ACCOUNTANT’S ability to 
buffer entries in memory allows a reporting program to open the file for read 
(which locks out ACCOUNTANT), while it generates it’s report. 

Adding a single record to the end of a file would result in a very fragmented file 
over a long period of time. To reduce this fragmentation, ACCOUNTANT will 
pregrow the file by 200 accounting entries each time the file becomes full. 


— 

0 

l_i_ 

lT 

lT_i 

L_i_J 

_5_ 1 

1 

o..pregrown... 


The first 4 bytes of record 0 contain the number of valid 
data records (as a long). Use fget(&lval, 4, fp) in C. 

The first accounting entry starts at record 1. 

The end of the file is pregrown with zero’s. 


[ACCOUNTANT] 
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ACCOUNTANT 


BUFFERED MODE 

If you do not specify any filenames on the command line, ACCOUNTANT will 
buffer all accounting entries. In this mode the b= option (if present) is ignored. To 
collect the accounting information you must write a program which sends 
messages to ACCOUNTANT, requesting the buffered accounting entries. The 
message consists of a single byte containing a message code of 3. The reply will 
consist of a msg_type followed by a 48 byte accounting entry. 

struct useraccsjtnsg { 
char msgtype; 

struct accstatentry accs data; 

*}5 

The the msg_type will be one of the following: 


Accs type 

Reason 

0 

Data returned ok. 

4 

No more buffered accounting entries. 

-2 

File mode, not buffered mode is running, 

-3 

Unable to save request. 

r4 

Bad message code in msg.type field. 


ACCOUNTANT registers the local name "account". This allows a task in a local 
area network to find and poll each ACCOUNTANT in the system. 

In both file and buffered mode, a task may send ACCOUNTANT 48 byte 
accounting entries. The msgjype code should be a 2 and the accs_type code must 
be greater than 2. These are written to the file or buffered depending on the mode. 
This allows special login/logoff programs to add extra accounting information. 

The accs_date field is always filled in by ACCOUNTANT. All other fields are left 
untouched. 

See Also: 

ACCSTATS 
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ACCSTATS - Print Accounting Statistics 


Syntax: 

accstats file ... [t-ttys\ [u -userid] [-stats] [-verbose] 

Options: 

t-ttys - Only print accounting information on these ttys, 

ii -userid - Only print accounting information on this user. 

TTie userid may be a pattern. 

-status - Suppress the status information. 

-verbose - Suppress the printing of each login/logoff. 

where: ttys = tty jange[,tty jange] 

ttyjange - ttyjium [: ttyjium] 

Examples: 

cd /acclogs 
accstats * 

accstats 8701 t=0,2,3-6 
accstats 870[1234] u=dtdodge 

Description: 

ACCSTATS is a utility which will print a summary of the accounting information 
saved by the ACCOUNTANT program. The above examples assume that file 
names are in the form yearmonth. This is a standard option available with 
ACCOUNTANT. 

See Also: 

ACCOUNTANT 


[ACCSTATS] 
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ALIVE - Set up/down status of a node 

Syntax: 


alive [[+]nidjist]* [- nidjist ]* [b =nidjist]* 

[a -nidjist]* [e=nidjist]* [n -targetjiode] 

alive [+busy] [+up] [+down] [+newboot] [n-targetjiode] 


WHERE 

nidjist is nid_range[,nid_range[,...]]* 
nid_range is nid[:nid\ 

Options: 


+nidjist 
nidjist 
b =nidjist 
a= nidjist 

e-nidjist 

+busy 

+up 

+down 

+newboot 

n -targetjiode 

Examples: 


These nodes are UP. 

These nodes are DOWN. 

These nodes are BUSY. 

Allow these nodes network access 
to this node. 

Don’t allow these nodes network access 
to this node (exclude). 

Inform POLLER that this node is BUSY. 
Inform POLLER that this node is UP. 
Inform POLLER that this node is DOWN. 
Inform POLLER that this node has booted. 
Node on which to change up/down 
status (default: this node). 


alive - Display current up/down status of all 

nodes. 

alive n=3 - Display current alive status of node 3. 

alive +2 - Node 2 is up. 

alive “5,6,7:12 - Nodes 5, 6 and 7 through 12 are down, 

alive +2,3 b=6 - Nodes 2 and 3 are up and 6 is busy, 

alive -2 n=10 - Inform node 10 that node 2 is down, 

alive +n - Inform the POLLER that this node 

has booted. 

alive +b n=7 - Inform node 7 that this node is busy. 
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ALIVE 


alive e=l:10 a=7 - Exclude nodes 1 through 10 except 7. 



The ALIVE command may be used to manually indicate to your local machine 

which nodes are up, down or busy. This command should not be needed if the 
POLLER is running. 

The first form of the alive command will set the local up/down status, unless the 
n= option is used. The second form will inform the POLLER by default unless the 

n= option is used. 

The operating system will not initiate any communications with another node 
unless it thinks that node is UP. 

When a node changes from UP to DOWN, the operating system automatically 
releases any resources which were being used by tasks on that node (usually files), 
and unblocks any local tasks which were waiting for messages from tasks on that 
node. This cleanup does not take place on the transition from UP to BUSY, or 
BUSY to DOWN] 

BUSY status is useful to temporarily remove a node from the network without . 
releasing any resources on other nodes. This might be done on a node before using 
the debugger to prevent the POLLER from flagging the node as down. 

alive +busy 

When the debugging session has ended, the alive command can again be issued to 
tell the poller that the node is now UP and ready to receive communications from 
other nodes. 

alive +up 

When a node is first booted, it is usually a good idea to inform die poller that the 
node is now up. The poller will then transmit this information to all other nodes in 

the network. To achieve this, the following command can be included in the file 

"/config/sysinit" for your node: 

alive +n 

The POLLER is responsible for scanning all nodes which are alive and ensuring 
that they are capable of receiving communications. If a node fails to respond to the 
poller in a reasonable amount of time, it is marked as DOWN and all other nodes 
are informed. This has the effect of releasing any resources which this node may 
have been using anywhere on the network. 


[ALIVE] 
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ALIVE 


The a= and e= options inform the operating system on this node to prevent or 
allow network accesses from the nodes specified in the list. This permits "clusters" 
of nodes to co-exist on the same physical network without interfering with each 
other. This facility also provides a measure of security on larger networks. 

The ALIVE command only applies to the network version of QNX. 

See Also: 

KILLVCS 

NACC 

POLL 
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APB 

APB - Send a Public Bulletin 

Syntax: 

apb message 

Examples: 

apb The pizza’s here!!! 

apb Cartridge disk two is now mounted! 

Description: 

The APB command will try to display a message on every terminal of every node 
in a QNX network. Each user will receive the message at the next convenient 
time. The SHELL will print the message, for example, just before it prompts for a 
new command. 

If another APB is sent before the first one is printed on a terminal, the second 
message will replace the first message. 

See Also: 

BEEP 


[APB] 
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BACKUP - Backup Files to a backup diskette 

Syntax: 

backup srcjiirectory dest directory [options]* 

Options: 


c=0 

€=1 

C=X 

di-date 

g=group 
m -member 

l=levels 

P =[ h ]pattern 

pd =[ A ]pattern 
s=[c][d][p] 

t -time 

4-all 

4-before 


- Copy only those files which have not changed since the last 
backup. 

- Copy only those files which have changed since last backup 

(default). 

- Ignore change status. 

- Copy only files which have changed since this date. Date is 
of die form dd-mm-yy (default date is 1-1-80). 

- Copy only files which have the indicated group number 
(decimal number from 0 to 255). 

- Copy only files which have the indicated member number 
(decimal number from 0 to 255). 

- Specifies how many levels of the specified source directory 
will be copied. Typically "1=1" is used to cause only the 
files at the current level to be copied. This option is 
particularly necessary when copying a directory to some 
sub-directory of itself (default is all levels). 

- Indicates that only files with names that match this pattern 
are to be copied. Multiple "p=" options are allowed, in 
which case files which match ANY of these patterns will be 
copied. Also, if the pattern is preceded by an up-arrow ( A ), 
then files which match this pattern will NOT be copied. 

- Indicates that only directories with names that match (or 
don’t match) this pattern are to be copied. 

- Suppress the copying of the 

date 

permissions (includes group/user numbers) 
and/or 

clearing of the changed bit on source file. 

- Copy only files which have changed since this time on the 
given date. Time is in the 24 hour format: hh:mm:ss 
(default time is 0:0:0). 

- Equivalent to c=x 

- Change the meaning of the date and time options to mean 
before. The default is now or after. 4-newest 
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BACKUP 


-cdireetory 


-cfile 


-error 

-pause 

-verbose 

■f write 
-fquit 

Examples 


the destination file is newer than the source, then do not 
copy; keep the newest of the two. 

If the directory does not already exist on the backup disk, 
prompt the user if he wishes to create it, skip it or retry after 
changing diskettes. The default is to always create 
directories as required. 

If the file does not already exist on the backup disk, prompt 
the user if he wishes to create it, skip it or retry after 
changing diskettes. The default is to always create files as 

required. 

Suppress message and prompt upon error condition. 
Suppress prompt (don’t pause to load disks). 

Turn off verbose option. This stops the BACKUP command 
from displaying the names of the files it is copying. 
Overwrite READ-ONLY files as well. 

Abort on error. 


backup 

backup 

backup 

backup 

backup 


3:/ 1:/ - Backup all files from drive 3 to drive 1 which 

have been modified since last BACKUP. 

3:1 h/ -cf -cd - Backup from drive 3 to drive 1. If files or 

directories don’t already exist on drive 1, then 
ask user if they should be created. 

/user/joe /user/bilS +a s=c 

- Copy all of joe’s files to bill’s directory 
without changing the modified state of joe’s 
files. 

2:/dirl l:/dirl p=*.c p= A test.c 1=1 

- Copy files under /dirl on drive 2 to the same 
directory on drive 1. Only copy modified files 
which end in ".c" except "test.c". Don’t copy 
sub-directories. 

3:/user [2]l:/user d=14-8-84 t=9:00 

- Backup files from 3:/user to 1 :/user on node 2. 
Copy only modified files which have changed 
since 9:00 am on 14-Aug-84. 



BACKUP provides a mechanism for backing up files. The decision to back up a 
file can be based on a number parameters. The default is to backup only those files 
which have changed since the last time backup was used. The d=, g=, m= 5 p=, 
pd= and t= options are by default don’t care conditions. 


[BACKUP] 
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BACKUP 


Typically, a user will use the BACKUP command to copy all of the files which he 

has changed onto a backup diskette. This eliminates the need to copy every file 
onto the backup diskette at the end of every session. Only die changed files are 
copied, which can be far less time consuming than an entire disk copy. This also 
allows selective files or directories to be restored from a backup diskette. The 
date, permissions and owner are be default copied to the backup files. The LS 
command can be used to highlight those files which have been modified since the 
last backup. 

Is 4-modified 

As an example of using the BACKUP utility, consider a user who is developing a 
rather large application consisting of several C source programs. These programs 
may all reside on one disk under a directory called "/work". During the course of 
his day he will change many files, and create several object files as a result of 
compiling these files. The object files need not be backed up since they can always 
be created again from the source files. If he uses the naming convention that all C 
source programs end with M .c M , and all object files end with M .o", the user could 
backup only his C programs by typing: 

backup /work /backup p=*.c 

The backup command will by default only transfer the files which were changed 
since the last backup. After backing up each file, BACKUP will clear the modified 
bit on the file. If you wish to save every file you may specify either m=x or +all. 

BACKUP is also handy for copying entire directories (with the +a option) on the 
same disk. In this case it is desirable to suppress the clearing of the modified bit 
since you are using backup more as a move command than a backup command. 

backup /dirl /dir2 +all s=clear 

Filename patterns can be any valid filename, with the following "wildcard" 
characters: 

* will match any character^ or run of characters 

? will match any one character 

[ccc] will match any of the characters in the brackets 

Some examples of filename patterns are: 

p=*.* any file with a dot (.) in it 

p=*.[ch] any file ending in V or V 

p=?a any two character filename ending in ’a’ 
p=[abc]* any file starting with ? ayb 9 or V 
p= A *„o any file which doesn’t end in to 9 
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BACKUP 


In cases where a directory is larger than the diskette, it is sometimes necessary to 
backup the files to different physical diskettes. The p= option may be used to 

select files. 

backup /util l:/util p=[abcdefghijkl]* 
backup /util l:/util p=[mnopqrstuvwxyz]* 

Once you have created a backup disk the -cf and -cd options will then allow all 
files to be backed up, prompting the user to insert the proper backup diskette as 
required. 

See Also: 

COPY 

FBACKUP 

TBACKUP 


[BACKUP] 


Utilities 



BAR - Draw Bar Charts 

Syntax: 

bar filename[field]* options* 

Options: 


field - Which field to plot. 

-border - No border around the graph. 

+grid - Draw horizontal grids. 

+high_res - Use high resolution graphics mode. 

+hres - Force to CGA 640x200,2 colour resolution. 

+Hres - Force to EGA 640x350,16 colour resolution, 

-legends - Don’t include legends. 

+line - Plot line graphs. 

+mres - Force to CGA 320x200,4 colour resolution. 

+outline - Draw outlines around each bar. 

-relative - Don’t draw relative to baseline if 
b= option is specified. 

+shade - Shade bars instead of fill in colour. 

+vstack - Stack bars vertically. 

-ylabels - Don’t draw labels on the y axis, 

a =char_angle - Angle of label characters (degrees) 
b -baseline - Draw a baseline at this value. Bars 

will be drawn relative to this line 
unless -r option is used, 
c ^colours - Only use this many colours, 
f =field - Which field of the current file to plot, 

g =gridscale - Only use this many colours. 

l=labels Jile - Label x axis with labels in this file. 
m-graphmode- Graphics mode to use. 
p =printjomd - Create hard copy printout via this 
command. 

t=text - Label the Plot with this title. 

x=xsize - Limit x axis to this size. 


y =ysize 
n=legendn 


Limit y axis to this size. 

Replace legend n with this name. 


(eg: "l=sales" "2=1985 YTD") 
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bar graphl 

bar apples peaches pears 
bar pigs cow sheep +v +H +s 

bar sales l=months 

bar plotl -y -1 
bar 1985 1986 b=37 0 6 
bar tl t2 13 b=10.0 +r 

bar data,l data 9 2 data,3 +1 
bar test "p=dump_ibm [2]$lpt ! 


Plot data in graphl 
Plot side-by-side 
High resolution shaded 
plot stacked vertically 
Plot with labels on the 
horizontal axis. 

Plot with no labels or legends. 
Plot 2 files with a baseline 
Plot 3 files showing deviation 
from a baseline. 

Line graph of 3 fields. 

Plot graph and create hard 
copy on node 2’s printer. 


BAR is a business graphics utility which draws bar charts based on information in 
one or more files. 

BAR requires that a GRAPHICS LIBRARY and a FLOATING POINT LIBRARY 
be mounted before using. The utility will determine the best dimensions and choice 
of colours depending on the installed graphics library. Vertical and horizontal 
dimensions can be reduced using the x= and y= options. BAR will attempt to use 
the highest resolution mode which is supported by the currently mounted graphics 
library. The +h, +m, and +H options can be used to force a particular resolution. 
The m= option can also be used to force a resolution. 

The information in each file is processed, using the FIRST field on each line of the 
file (unless another field is requested). The remainder of the line can be used for 
comments. The number of bars to draw is determined from the file which contains 
the maximum number of lines. The width of each bar is adjusted automatically to 
provide the best plot. The plot is automatically scaled in the vertical dimension to 
accommodate the largest entry. 

A border is drawn around the plot unless -b is specified, with appropriate grid 
marks drawn on both left and right borders. The vertical axis is labeled 
automatically with the minimum and maximum values unless -y is specified. If a 
grid is requested (+g), then only the grid lines are labeled. The grid scale is 
selected to best fit the data. Different grid scales may be chosen using the g= 
option. 


[BAR] 


Utilities 



BAR 


The orientation of the label characters can be changed with the a= option, although 
this is seldom useful. 

Each graph is assigned its own colour where possible unless shading is requested 
(+s), in which case each graph will be assigned a unique style of shading. The 
graphs are plotted horizontally by default (normal bar chart) unless the vertical 
stacking option is specified (+v) in which case the graphs are stacked on top of 
each other. The scale will be adjusted automatically for vertical stacking. Negative 
values are forbidden in vertical stacking mode. 

Legends will be drawn on the bottom of the graph, unless the -1 option is used. The 
legends can be customized using the 1=, 2= and similar options. If no legend is 
specified, the name of the file will be used. 

Relative plots with respect to a baseline are drawn if a baseline is given (b=) and 
the -relative option is NOT specified. Relative plots show the bars as eitiier posi¬ 
tive or negative changes from the baseline. Relative plots are not allowed with 
vertical stacking (+v). 

The horizontal axis can be labeled by using the 1= option to specify a file 
containing horizontal labels. This could be, for instance, a file consisting of the 
months of the year. Extra elements in the label file will be ignored. 

Line graphs are plotted if the +line option is specified. Dashed lines will be used if 
+shade is also specified. 

Hard copy can be obtained by specifying the name of a command which will make 
a copy of the graphics device, once the plot is completed. BAR pauses when the 
plot is finished, and if a command has been specified with p=, win call that 
command if the user types the character p (for print). Any other character will 
cause BAR to terminate without creating hard copy (see the last example). 

Most of the command line options can also be embedded within the file being 
plotted. Any line which starts with an opening square bracket ([) will cause BAR to 
parse the string within the brackets as if it were typed on the command line after 
all the other arguments. 

Any line starting with a double-quote (") is ignored, so can be used as a comment 
line. 

Any line which starts with characters enclosed in round brackets () will use those 
characters as a label for that entry. The data within round brackets will otherwise 
be ignored. 
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All remaining tokens on a line are treated as files to be plotted. 

The simplest form of a data file is simply a list of numbers, in one or more 
columns, such as shown below: 


56.1 

26.1 

9 

1 

43.1 

22.2 

8 

9 

45.7 

18.2 

8 

8 

39.4 

16.7 

9 

0 

35.5 

16.3 

8 

7 

30.9 

14.1 

8 

5 

28.6 

10.0 

8 

3 

29.2 

11.0 

8 

8 

34.3 

10.1 

9 

1 

37.3 

15.5 

9 

0 

45.7 

20.3 

9 

3 

50.0 

24.4 

9 

0 


The 3 fields of this file could be plotted as a STACKED BAR graph using the 
command: 

bar file,l file,2 file,3 +v +g "t=1987 Production" 1=H/W 2=S/W 3=Other 

If this file is always plotted with the same arguments, you could choose to embed 
the parameters within the file, by putting the following lines at the beginning of the 


" field 1 is plotted first 

[f=2] 

[f=3] 

[+v] 

[+g] 

[t=1987 Production] 

[1=H/W] 

[2=S/W] 

[3=Other] 

With these extra lines, the same plot will result from the command: 
bar file 


In order to demonstrate the capabilities of BAR, the above data was used to 
generate the following actual untouched graphs: 
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bar file,l file,2 file,3 +g "t=1987 Production" 1=H/W 2=S/W 3=Other 
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STACKED,BAR GRAPH 



bar fiie»lfile»2 fiie,3 : +g +v "t=1987 Production 11 1=H/W 2=S/W 3=Other 
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BAR 


LINE GRAPH 



bar file,l file,2 file,3 +g +1 "t=1987 Production" 1=H/W 2=S/W 3=Other 


See Also: 

DUMP_IBM 

MOUNT 
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BEEP - Beep a user on another terminal/machine 

Syntax: 


beep userid [ message ] 
beep [node] tty [message] 



userid - A user signed on in the system. 

node - A node within a QNX network. 

tty - The tty number to beep. 

message - Message to send. 



beep gord 

beep gord Its time for lunch 

beep 3 Please get off the modem port 

beep 1 3 Please get off the modem port on node 1 

Description: 

BEEP will send a message to a user. The user may be logged in on the console or 
any terminal in the network. A stand-alone system is considered as a single node 
network. If the message is omitted, the user will only receive a series of beeps to 
attract attention. The user might then drop into CHAT or MAIL. If a message is 
specified, it will be printed at the current cursor position on the user’s screen. This 
may cause minor confusion if the user was running a full screen application like 
ED. The beeps will be sent right after the message is displayed. 

Note that BEEP opens the user’s screen for write. If the user has partially typed in 
a line, then BEEP will wait for a carriage return. If a user is signed on more than 
once, the message will be delivered to each screen the user is logged onto. 

See Also: 

APB 

WHO 
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BOOT - Select an OS file for disk booting 

Syntax: 


boot osjilejiame [options]* 

Options: 

-pause 

4-qnxloader 
-qnxloader 
c=config Jile 
d -disk_driver 

ROM Boot options: 

+Hard_disk - Hie disk is going to be a hard disk device. 

+F loppy disk - Hie disk is going to be a floppy disk device. 

■Partition - Is a partitioned disk and the boot loader will 

be made aware of this. 

-Partition - Is not a partitioned disk and the boot loader will 
be made aware of this. 

Examples: 

boot 1 :/netboot/os.2. lOatp 

boot 3:/netboot/os.2. lOatp d=/drivers/disk.at +q 

boot 3:/netboot/os.2.10atp 

Description: 

BOOT selects the name of a file you wish to boot from disk. The disk may be a 
floppy' or a hard disk. 

To understand the purpose of title +qnxloader, some background information on 
hard disk booting is necessary. 

Booting from hard disk is a two step procedure. The BIOS first reads in block one 
of the hard disk and transfers to a bootstrap loader which decides which of the 4 

partitions is active. This loader reads in the first block of the active partition and 
transfers to another bootstrap loader. This loader is operating system specific, and 
loads in the operating system for that partition. 


Don t pause. 

Write the special QNX loader. 

Remove special QNX loader. 

A configuration file to bind into the OS. 
A hard disk driver to bind into the OS. 
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BOOT 


Block 1 
of disk 

Partition 1 

Partition 2 

• • • • 

+qnxload 

OS 1 

Os 2 


level 1 

level 2 

level 2 


loader 

loader 

loader 



The first level bootstrap loader as provided by DOS will always boot the active 
partition as set by the QNX or DOS FDISK program. If you specify the 
+qnxloader option, we will replace this bootstrap with one that will still default to 
the active partition, but will pause for several seconds and allow you to override 
from the keyboard by typing a single digit from 1 to 4. This gives more 
flexibility. If you have non-standard hardware, or are already using a special 
loader, then this loader may cause you problems. For 99.9% of all installations we 
recommend you use the QNX loader. You need only specify the +qnxloader op¬ 
tion once. 

When you specify +q option, BOOT looks at the partition loader already on the 
disk (probably DOS’s) and if it is different than the QNX loader, saves it away to a 
file called / config/hdiskMr . Then, at any time in the future, if you use the new -q 
option, you can restore the original loader back to the partition sector. 

When QNX boots, it needs a hard disk driver in order to access the hard disk. 
Unlike DOS it cannot use the BIOS driver which does not work in protected mode. 
You must specify which hard disk driver to bind into a hard disk boot. This is 
done using the d -disk_driver option. This option takes the name of a mountable 
disk driver, and creates a file called /config/hdisk.cfg which will be loaded in from 
hard disk along with the operating system file. You need only specify the d=driver 
option the first time you configure for hard disk booting. 

You may have several OS image files under the directory /netboot, and you may 
use the BOOT command to select which one you wish to boot from. This is very 
handy if you download a beta version of an OS from the QNX Update System and 
wish to try it out. 

boot /netboot/testos - Select a test version to boot 

The BOOT command also allows you to specify a configuration file which lets you 
change some of the operating system defaults; such as the number of open files 
supported. This is specified as a c=filename option. You may select any file 
name, however we recommend that you choose names like those shown below. If 
you boot across a QNX network, then you must use a name as shown below. 
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/conflg/sys.cfg - Single machine. 

/config/sySoCfgoiiii - Network machine* 

The sys.cfg file is created and maintained by the OSCONFIG command, ft takes 

the file name as an argument. For example 

©sconftg 3 "/conflg/sys.cfg 

would create a configuration file for a single non-networked machine. It does not 
become active until you use the BOOT command to set it. 

boot 3:/netboot/os.2.10pcat c=3s/config/sys.cfg 

NOTE: Once booting from hard disk, you should not remove the O/S file, the 
driver file or the config file. 

Inethootlosname 

/config/hdisk.cfg 

/conflg/sys.cfg 

You may copy a new file on top of them but NEVER remove them (FREE, RM, 

...) and then create a new one, even if they have the same name. The BOOT 
command saves away the absolute start blocks of each of these files, which will 
change if the file is removed. 


ROM BOOT options : 

+Hard_disk 

The boot disk is going to be a hard disk device. This option conditions the boot 

loader so that it uses the hard disk BIOS read call instead of the floppy disk BIOS 

read call (ie: register dl has 0x80 ’or’ed in for the read). 

+Floppy 

The boot disk is going to be a floppy device. This option conditions the boot loader 
so that it uses the floppy BIOS read call instead of the hard disk lead call. (ie: 

register dl does not have 0x80 ’or’ed in for the read). 

+PartItIon 

The boot disk being prepared is a partitioned disk and the boot loader placed on the 
disk will be made aware of this. Normally, floppy and ROM disks would not use 
this option. 
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-Partition 

The boot disk being prepared is not a partitioned disk and the boot loader placed on 
the disk will be made aware of this. Normally, floppy and ROM disks would use 
this option. 

These options should be used to descibe what the ultimate ROM disk will boot as, 
and should not necessarily describe the media the boot command is executed on. 
For example, if you had a ROM disk driver that acted like a hard disk, you would 
use the +H option, even though you were preparing the ROM image on a floppy 
disk. 

See Also: 

NETBOOT 

MOUNT 

OSCONFIG 
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BREAK - Break a task 

Syntax; 


break task-id 

• This is a local shell command • 

Description; 

BREAK allows a task whose taskid is known to be killed gracefully. The taskid 
can be found by using the TSK command. Only tasks which are created by 
yourself can be broken. The super-user can break any task in the system with the 
exception of the operating system and user administrator tasks. 

BREAK is typically used for aborting background programs since they are no 
longer associated with a terminal, and therefore cannot be terminated with the 
BREAK key. A background LIST program is an example of a task which a user 
may wish to break. 

BREAK is the preferred method of killing tasks, since KILL will not allow a task 
to terminate normally, so may result in devices or files being left in an 
indeterminate state. BREAK will usually only kill a task which manages critical 
resources at a time where it is safe to do so. 

See Also; 

KILL 

SLAY 

TSK 
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CALC - A simple calculator 

Syntax: 

calc [+full_screen [rows columns ]] 

Options: 


+full_screen - Full-screen/interactive mode. 

rows - Number rows for calculator "window”. 

columns - Number columns for calculator "window". 


Examples: 

calc 
calc +f 
calc +f 10 35 

Description: 


- Drop into calculator. 

- Invoke full screen mode. 

- Invoke CALC in 10x35 window. 


. CALC performs a simple desk-top calculator function. 

CAUTION: before CALC can be used, a floating-point shared library must have 
been installed: 

mount lib /config/floatslib 
or 

mount lib /config/fioat8087.slib 

CALC evaluates expressions with internal double precision accuracy. This results 

in 15 significant digits of accuracy, and values between 4.19E-307 to 1.67E308 
being supported. 

Numerical constants can be entered in standard arithmetic form, or as Octal, 
Hexadecimal, or ASCII character constants: 


10 - the number 10 

l.le-37 - the number 1.1 x 10**37 

$123abc - a Hexadecimal number 

@17777 - an Octal number 

’A - the ASCII character ’A’ (0x41) 
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Within .the; calculator, expressions are entered in algebraic form (NOT reverse 
Polish). Brackets may be used to group expressions. The following arithmetic 
operators are supported: 

+ AM 

Subtract ' . ' • 

* Multiply 

/ Divide . 

CALC supports 26 registers identified by the lower-case letters ’a’ through ’z\ 
Values are stores into registers with the character. For example: 

p = 3.1415926 / 2 

Registers can be used anywhere a number can be used: 

360* (.707+p) 

While entering data, you are free to edit the line using the left arrow, right arrow, 
Ins, Del, and Rubout Keys. In addition, the UP arrow key can be used to recall the 
previous line, which can then be edited. 

To terminate CALC in interactive mode, type Ctrl-D. 

In full-screen mode, the following screen will be displayed: 


I CALCULATOR 


Use the function keys to: 

FI make the calculator 
invisible; 

F9 move the calculator using 
the cursor keys; 

F10 quit. 

> 


As shown, the FI, F9, and F10 keys have special meaning. 
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When F9 is typed, CALC will indicate that it is in move mode with an asterisk in 
the upper left comer of its "window”. The keypad arrow keys can then be used to 
move the window around the screen. When the "window" is where you want it, 
type F9 again. 

If the CALC window is hiding some part of the screen you wish to see, you can 
type FI to make CALC temporarily invisible. Typing FI again will re-display the 
CALC "window". 

See Also: 

PRTSC 
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CAT - Concatenate input files into one larger file 

Syntax: 


cat [inputJile]* [>outputJile] 

Examples: 

cat smalll small2 >big 

cat filel flle2 file3 file4 >massive 

cat file 

cat filel - file2 >new 
cat >easy 

Description: 

CAT will concatenate a list of files creating one larger file. The default output is 
the standard output (usually the terminal), which the user will typically redirect to 
a file or line-printer. 

The standard input (keyboard) can be specified with a dash (-) which will cause 
CAT to insert data taken from the standard input until an end-of-file (Ctrl-d on 
keyboard) is encountered (as shown in the example). Also, you can quickly 
create a file without an editor by using CAT, as in the last example, which will 
read data from standard input until end-of-file. 

See Also: 

SPLIT 
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CC - Compile Command (C, Basic,...) 

Syntax; 

cc file [options]* 

Options: 


+Asm - Do not ran the asm command, and retain the 
.a file (asm input). 

-core - Do not ran the link command even if only one 

source file is entered, and retain the .o file 
(link input). 

-Core - Same as -core. 


-Exec - Don’t execute any commands (debug). 

- Include any libraries needed for source modules 
ending in the suffix c. (see +W c option) 

-Nested - Nested comments will all terminate on first 
^ Usually every nested level requires its own end sequence. 

+Optimize- Run the "C" optimizer. 

+optimize - Run the "C" optimizer. 

-preproc - Do not ran the C preprocessor (CPP) (default). 

4-preproc - Run the C preprocessor (CPP). 

-i-Preproc - Only ran the C preprocessor leaving the output 
in the same name with the suffix capitalized. 

For example test.c -> test.C 
test.b -> test.B 

•fQbug - Create symbol tables for a symbolic debugger. 

-Remove - Don’t remove the temporary files. 

-Stackchk - Suppress the stack checking code produced by 
the code generator, (same as +Wi,s=0) 

-Tmp - Do not use /tmp as the work directory. 

Temporary files will be created in your current 
directory. 

-Verbose - Suppress the printing of each phase of 
compilation. 

+Verbose - Very verbose output. 
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+8087 - Force the code generator to produce native 8087 

code for floating point operations. During link 
the native 8087 system libraries will be 
searched. The default is to generate software 
interrupts into a floating point shared 
library. Native code requires an 8087/80287 
but can be as much as 500 times faster. 

+W c 9 arg - This option is used to pass the argument 
(arg) to a specific processor (c) as follows: 

? cpp C pre-processor 

a asm assembler 

b cbl basic parser 

c ccl € parser 

I cc2 code generator 

y yacc yacc 

encore - Specify name of compiled loadfile. 

E =obj.o - Use the indicated object module in place of 
the system one in /lfb/entry.o. 

0=objdir - Place all object modules in the indicated 
directory rather than, the current directory. 

. T =treesiz - The parsers and code generator build parse 
trees in internal tables. Very complex 
expression may require you to increase this 
space. The default is 2500. 

+386[/16] - Internal use only. 

The following three arguments cause the optional € 

preprocessor to be invoked (forcing +p)» and are used 

as follows: 

d e=name=value - Works as if "#define name value" was in 
the source. 

tin -name - Removes any "#define name " implemented by the 

C preprocessor. 

in =dir - Adds dir to the automatic library search 
for #include <name.h> files. 

Examples: 

cc hanoi.c 

Compile hanoi.c and create an executable program in the current directory 

with the name hanoi. 
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cc hanoi 

One by one append the following suffixes to the file hanoi, {.c, .b, .y, i, .a} 
and on a match invoke the appropriate parser. If the file hanoi.c exists, then 
this will have the same effect as the previous example. 

cc clock.c -S 

Compile clock.c and create an executable program in the current directory 
with the name clock. The program will not contain stack checking code. This 
will make it slightly smaller and faster. 

cc clock.c +Wc ? e=error§ 

Compile clock.c and create an executable program in the current directory 
with the name clock. Any errors detected during compilation will be placed in 
the file errors. 

cc prtsc.c c=/cmds/prtsc +V 

Compile prtsc.c and create an executable program in the /cmds directory with 
the name prtsc. 

cc banner.c -c de=fimction=l 

Compile banner.c using the optional preprocessor to add ”#define function 1” 
and retain the output banner.o in the current directory, (link was suppressed) 

cc fastprog.a -c +Wa,+286 

Assemble fastprog.a program and pass the argument +286 to the assembly. 
The link was suppressed and an object module fastprog.o will be produced. 

cc baslc.b csub.c 

Compile basic.b and C function csub.c producing two object files (. 0 ). The 
two object files will be linked and, because a basic program was compiled, the 
basic run time library "/blib" will be included during the link. Since more than 
one file was specified, the executable will be in a file called core. 

cc basic.b csub.c c=basic.test 

Same as above but executable (core) placed in basic.test. 

cc *.c /mylib/fun.o +Lb 

Compile all C programs in the current directory. Object modules (. 0 ) will be 
produced for each C program. The object modules will be linked along with 
/mylib/fun.o creating an executable load module called core. Search Basic 
libraries. 

cc *.0 

Pass all object modules to the linker and produce an executable load module 
called core. Don’t forget the +8087 option if you wish inline 8087 code. You 
may also need to specify the +Lc option to search language dependant 
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libraries. 

cc x=ofiles 

Invoke the linker with the option x=ofiles. 

Description: 

CC is the QNX compiler interface. It takes a list of source and object modules on 
the command line and invokes the appropriate parser to compile each file. Object 
modules are passed straight through to the linker. The choice of parser to use is 
based upon the file suffix. 

x -> C compiler /emds/ccl 

Jb -> Basic compiler /cmds/cbl 

*a -> Assembler /cmds/asm 

j -> Yacc /cmds/yacc 

A -> Code generator /cmds/cc2 

The parser must exist in order for you to use it. The CC command was designed to 
work with potential future parsers and may contain entries for parsers which are 
not yet available. If the suffix on a file is omitted, a scan for a file with each of the 
possible suffixes is made. Upon a match the appropriate parser is invoked. The 
suffixes are scanned in the following order. 

x -> -> „y -> i ~> „a 

If only one source file is given, the linker will create an executable program in the 
current directory, with the same name as the input file, but with the suffix stripped 
off. If more than one file is specified, the executable will be placed in the file core. 
You may use the linker option c -name to force the destination of the executable. 

The -core option will suppress the LINK phase. This is a heavily used option by 
developers which have many separate source files which they update and modify 
individually. 

There are special system libraries for each parser which will automatically be 
included in the link when a source module for that parser is encountered. If only 
object modules are specified, then only the standard C libraries will be searched. 
You can include libraries using the +Lc or l=library option which is passed to the 
linker. ■ 

cc *.o 1=/Mib (or use +Lb option) 

or 

cc x=oflles I=/blib (or use +Lb option), ' 
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The code generator is capable of generating either native 8087 code or calls into a 
mounted shared library for floating point operations. The default is to emit calls to 

the shared library. This allows a program to ran on a machine which does not 
contain an 8087 co-processor. One of two shared libraries may be mounted. 

mount lib /config/float.slib (no 8087) 

or 

mount lib /config/float8087.slib (8087) 

The second shared library is an order of magnitude faster than the first. Note that 
this approach allows you to distribute one program which can take advantage of 
the 8087, if it exists, or use software emulation if it does not. For really time 
critical operations, the overhead imposed by the shared library can be avoided 
completely by specifying the +8087 option, which will cause the code generator to 
produce native inline 8087 code. This switch will also link in the native 8087 math 
libraries. No shared library need be mounted but an 8087 MUST be present. 

The QNX C compiler contains a limited C preprocessor which should handle 98% 
of all C programs. By building the preprocessor into the parser, it eliminates one 
phase, resulting in a faster compilation. You may use the full implementation of 
the C preprocessor by specifying the +p option. Very large programs may cause 
the C parser (ccl) to ran out of memory due to a large number of #defines. Each 
define takes up memory. In this case the preprocessor will strip the #defines, 
giving the parser more memory to work with. 

In some cases complex defines or macros may produce parser error messages 
which are difficult to understand. By using the +P (capitalized) option, the 
expanded output will be left in a file with the same name, but with the suffix 
capitalized. You may examine this file with the editor. 

The full implementation C preprocessor also implements a number of built-in 

manifests including: i8086, qnx, quantum, DATE , FILE , and LINE . 

_DATE is a string containing die date the file was compiled. FILE and 

_LINE_are dynamic manifests containing the filename and linenumber of the 

source. 

You may occasionally wish to examine the assembly code produced by the code 
generator, maybe in attempt at optimization or perhaps in tracking down a 
suspected code generator bug. The +Asm option will stop the compile after cc2, 
leaving a file with the suffix .a. 

The -Stackcheck option will suppress the generation of stack overflow code by 
cc2. This typically results in slightly smaller and faster code. We recommend that 
you leave stack checking on for files that contain recursive functions. 
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All arguments and options that are not listed above are assumed to be instructions 
for the linker and will be passed to the LINK command. Object modules (files 
ending in .o) are also passed directly through to the linker. The choice of upper 
case options is deliberate to avoid confusion with options known by the processors 
(parser, code generator, assembler and particularly the linker) invoked by CC. For 
example, you can change the default stack size by specifying s =stacksize which 
will be passed to the linker. The default of 2000 bytes may need to be increased for 
recursive programs or programs which place large arrays on the stack. If possible 
move arrays outside of functions to avoid having to override the stack size. 

If you need to specify a parameter to any of the processors, you may use the 
+Wc,option. Check die documentation on each processor to determine its options 
or type its name followed by a question mark (?). 

ccl ? 


The following charts illustrates the flow of control for the different parsers 
invoked. 

WITHOUT THE PRE-PROCESSOR 

.y .c .i .a .© 

yacc ' ccl■ 1 cc2 1 asm ' link 

.b . i A A A 

- obi - 1 I I 

.a 


.o 


WITH THE PRE-PROCESSOR 

•y .c .C .± .a .o 

yacc - cpp “ ccl - cc2 .-- asm - link 

.b ,B .i A A A 

cpp cbl - 1 I I 

• a 


.o 
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See Also 


LINK 
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CD - Change current Directory 



directory - Name of new directory. 

Examples: 

cd /user/bill 
cd 3:/expl 
cd [4]3:/user/dan 
cd 


• This is a local shell command • 


Description: 

CD allows the user to define his working directory. All file names which do not 
start with a slash (/) or a drive number, are assumed to be relative to the current 
working directory. The default working directory is defined when the user logs into 
the system. Issuing CD with no arguments will restore the working directory to the 
initial login directory. 

CD allows the user to position himself anywhere in the QNX hierarchical file 
system. If a QNX network is available, then this can be on any disk of any 
computer in the network. CD eliminates the need to always specify complete 
pathnames. 

For example, if a user "bill" has a directory called "work" which contains several 
files he is currently working on, he can specify the name of one such file as 
"/user/bill/work/file 1". This is the complete pathname of that file. 

Alternately, he could set his current directory by typing: 

cd /user/bill/work 


[CD] 


Utilities 



CD 


He can now reference the file as simply "filer’. Since the user "bill" is initially 
working at the directory "/user/bill" when he logs in* he could have typed: 

cd work 

to move himself down one level to the directory "work". 

When he has finished working on the files under directory "work"* he can move 
back up to his previous working directory by issuing: 

ci A 

The PWD command can be used to display the current working directory. 

Every task which runs in QNX has its own current directory. When one program 
(like the SHELL) creates another program, the created program will initially 
inherit the current directory of its creator. This new program may then change its 
current directory. Keep in mind however, that when this program terminates and 
control returns to the creator, the new current directory will be lost, since the 
original program has never changed its own current directory. 

This fact is especially noticeable when SHELL files are invoked (BATCH files to 
DOS users). The SHELL file is controlled by a new SHELL task which has its own 
current directory (initially yours). If the SHELL file changes its current directory, 
then it will be changed only as long as that SHELL file is running. When it has 
finished, your current directory will be the same as it was before the SHELL file 
was executed. 

See Also: 

PWD 
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CHATTR 

CHATTR - Change Attributes of a file 

Syntax: 


Change attributes of file. 

Change attributes of directory. 

Change the group number of a file. 

Change the group member number of a file. 
Change name of file. 

Change file permissions (for my group). 
Change directory permissions. 

Change file permissions (for other users). 
Change directory permissions. 

Same as combined po= and pg= (files). 

Same as combined po= and pg= (directories). 
Change file status. 

Change date to current date. 

Make un-busy (Caution: see text). 


chattr filename* options* 



a=[+l»][rwaem] - 

a=[+l-][rcbm] 

g=group 
m= member 
m-name 

pg=[+l-][rwaem] - 
pg=[+l-][rcbm] - 
po=[+|-][rwaem] - 

po=[+H[rcbm] - 

P=[+l-][rwaem] - 

P=[+i-][rcbm] 

s=[+l-][bmu] 

+date 

-busy 



chattr old n=new 
chattr main.c g=12 m=4 
chattr core p=-wa a=+e 


chattr /user/bill +d 
chattr file.dat s=-b 


- Change name of "old" to "new" 

- Change ownership of file. 

- Remove write and append permis¬ 
sion from "core", add execute 
attribute. 

- Update date of file to today 

- Unbusy a file (Caution: see text). 


CHATTR allows the status, attributes, permissions, date, owner, 
to be changed. 

The status flags which can be changed on a file are 


and name of a file 


b - BUSY. Set when the file is opened for write. If the system crashes 
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without closing the file, this bit will be left set in the directory entry, 
m- MODIFIED. Set whenever a file is modified (open for W, R/W or A) 
and cleared by the BACKUP command, 
u - USED. This flag can only be cleared. It is the equivalent of zapping the 
file with the ZAP command. 

The attributes and permissions which apply to files are: 

r - READ. This capability allows files to be read or copied, 
w - WRITE. This capability allows data to be written into a file. Old file 
contents will be lost. 

a - APPEND. This capability allows new data to be written at the end of a 

file. The current contents of the file are not changed. 

. e - EXECUTE. This capability allows a file to be executed. All files created 

by the linker are created with execute permission. Any copies of an 
executable file will also need this permission before the file can be 
executed. 

m- MODIFY. This capability allows the CHATTR command to change die 

attributes, permissions, name, owner, and date of a file. If this option is 
ever turned off, the attributes can never again be changed. Modify permis¬ 
sion can only be turned off by specifying a=-m. Take care never to 
remove modify permission from a file which doesn’t have write permis¬ 
sion, or it will remain forever! 

The attributes and permissions which apply to directories are: 

r - READ. This capability allows directories to be read or listed, 
c - CREATE. Allow new files to be created under this directory, 
b - BLOCK. Prevent directory searches below this directory, 
m- MODIFY. Same as for files. 

Attributes of a file or directory apply to the owner of the file and the super-user 
(group 255). Permissions are those attributes which are permitted for other users. 
There are two types of permissions 

Group - these apply to members of the same group 
Other - these apply to members of other groups 

Careful setting of permissions on directories and files allows a user to "protect" his 
files from other users of the system in a multi-user environment. 

The owner of a file can be changed with the g- and m= options. These options will 
usually be used by the operator when creating initial user directories. The group 
and member number must be a number from 0 to 255. The owner (group.member) 
number is assigned to a user in the password file. Only the super-user can invoke 
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the g= option. The nt= may be used by the super-user (group 255) or a group 
leader (member 255 of a group). 

Filenames can be changed using the n= option. New names refer only to the lowest 
level of the complete pathname. For example, to change the name of die file 
"/user/joe/dirl/biU" (which has the name "bill"), one would use: 

chattr /user/joe/dir 1/bill n=fred 

Valid filenames contain 1 to 16 characters, consisting of upper or lower case letters 

(they are distinguishable), numbers, underscores (_), dots (.), and dollar signs ($), 
provided that $ is not the first character. 

The date and time of a file can be updated using the +d option, which changes the 
date and time stamp of the file to the current date and time. This is especially use¬ 
ful for upgrading files which were created or changed during a session where the 
user neglected to set the system date. 

Busy files can be made unbusy with the -b option. The command CHKFSYS 
should then be run to verify that the unbusied file is consistent. If not, the file 

should be copied to another file and the original zapped using "chattr s=-u" or 
ZAP. An inconsistent file should NEVER be left on a disk and should NEVER be 

released by using FREL. 

See Also: 

CHKFSYS 

ZAP 
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CHGRP - Change group (group number) of a file 

Syntax: 


chgrp group jiumber file * 

Examples: 

chgrp 4 fiiel file2 

Description: 

CHGRP changes the group number of the specified files to group jiumber. This 
number must lie between 0 and 255 inclusive. Group 255 is a the super group. 

Note that this is a shell file which invokes the CHATTR command. 

See Also: 

CHATTR 

CHOWN 
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CHKFSYS - Check entire file system for consistency 

Syntax: 


chkfsys drive [options]* 

Options: 


drive 

b=file - 
f-lpath - 
-stats 

+rebuild - 

-fix 

-pause 

-verbose - 


Disk drive on which to check file system. 

File of bad blocks.( see DCHECK utility ) 
Check the indicated pathname only. 

Suppress statistics calculation and display. 
Suppress error messages relating to the bitmap. 
Don’t fix anything. 

Don’t ask user if errors should be fixed. 

Don’t print names of files being checked. 


chkfsys 2 
chkfsys 2 +r 


Check file system on drive 2. 

Check file system on drive 2 in order 
to rebuild the bitmap. 



CHKFSYS will perform a consistency check of the file system on the requested 
drive. It will recursively walk the file structure visiting every file on the disk. 
During the walk checks are made on the directory entry of each file and the extents 
that make up the file. A bitmap is constructed in memory which is consistent with 
the block allocation of all files and directories on the disk. This bitmap is then 
compared to the one on the disk. If they differ the user is given the option of 
replacing the bitmap on disk with the one constructed in memory. 

IMPORTANT: CHKFSYS should only be used when the system is idle. There 
should be NO open files when CHKFSYS is running. 

CHKFSYS is usually used to recover blocks which were lost through the use of the 
ZAP and CHATTR command. 

zap file 

chattr s=-u file 
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In this case CHKFSYS will complain that there are blocks used In the bitmap 
which are In fact NOT used by any file. These blocks may be recovered by writing 
the reconstructed bitmap back to disk. CHKFSYS will attempt to read each of 

these blocks and will NOT mark bad blocks as available. 

The b= option may be used to inform CHKFSYS of known bad (or marginal) 
blocks. Each line of the file should contain 1 hexadecimal block number. The 
block numbers must be sorted in ascending order. 

If b= is not specified, then CHKFSYS will use the file "/bad_blks , if it exists on 
the drive being checked. This file is created automatically by the command: 

dcheck +mark 

CHKFSYS will tell you if any files are using blocks which are now known to be 
bad. 

If CHKFSYS complains that a block is used by more than one file, it could ^ 
indicate one of two problems. If the b= option was specified, or 7bad_biks” 
exists, then it probably indicates that the file uses a block which is bad and marked 
as used in the bitmap. If there are no known bad blocks, then a multiple allocation 
of a single block has occurred. In either case, the file should be saved on 
ANOTHER disk (if possible) and then zapped. CHKFSYS should then be ran 
again to update the bitmap, after which the saved file may copied back onto the 
disk. 

In general, whenever the bitmap is replaced, CHKFSYS should be run a second 
time to ensure that the file system is indeed consistent. 

CHKFSYS may also be ran after a system crash or power failure which has left 
some files busy. The files may be made unbusy using the chattr command 

chattr s=-b file 

which may then be followed by a CHKFSYS to ensure that no damage to the file 
system has occurred. QNX should be relatively immune to this type of damage. If 
CHKFSYS complains, you may copy the unbusied files to another disk, zap them, 
run CHKFSYS to recover lost blocks, then restore files. For example. 

copy 2;/filel l:/f!lel 

■ zap 2:/ft!el 
chkfsys 2 
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copy l:/fflel 2:/fiIel 

If you are crashing the system often while debugging a program, you may wish to 
always save, zap and restore files and only run CHKFSYS occasionally to recover 
bad blocks. If you are sure that no disk I/O was in progress, it is probably not even 
necessary to zap the files. 

If the f= option is specified, then only the indicated pathname will be checked. 

The pathname must start with a slash. This is not a complete check in that it 
cannot check for multiple allocations of the same block to more than one file. For 
example: 

chkfsys 1 f=/user/gord/data 
will check the file l:/user/gord/data. 

In the event of the complete loss of a file system due to the destruction of the root 
directory and the bitmap (first few blocks of the disk) you should refer to the 
technical note on file recovery in your QNX manual. 

See Also: 

DCHECK 

ZAP 

QUANTUM TECHNICAL NOTE ON FILE RECOVERY 
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copy l:/fllel 2:/filel 

If you are crashing the system often while debugging a program, you may wish to 
always save, zap and restore files and only run CHKFSYS occasionally to recover 
bad blocks. If you are sure that no disk I/O was in progress, it is probably not even 
necessary to zap the files. 

If the f= option is specified, then only the indicated pathname will be checked. 

The pathname must start with a slash. This is not a complete check in that it 
cannot check for multiple allocations of the same block to more than one file. For 
example: 

chkfsys 1 f=/user/gord/data 
will check the file 1 :/user/gord/data. 

In the event of the complete loss of a file system due to the destmction of the root 
directory and the bitmap (first few blocks of the disk) you should refer to the 
technical note on file recovery in your QNX manual. 


DCHECK 

ZAP 

QUANTUM TECHNICAL NOTE 01 FILE RECOVERY 
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In this case CHKFSYS will complain that there are blocks used in the bitmap 
which are in fact NOT used by any file. These blocks may be recovered by writing 
the reconstructed bitmap back to disk. CHKFSYS will attempt to read each of 
these blocks and will NOT mark bad blocks as available. 

The b= option may be used to inform CHKFSYS of known bad (or marginal) 
blocks. Each line of the file should contain 1 hexadecimal block number. The 
block numbers must be sorted in ascending order. 

If b= is not specified, then CHKFSYS will use the file "/bad_blks", if it exists on 
the drive being checked. This file is created automatically by the command: 

dctieck +mark 

CHKFSYS will tell you if any files are using blocks which are now known to be 
bad. 

If CHKFSYS complains that a block is used by more than one file, it could 
indicate one of two problems. If the b= option was specified, or "/badjblks" 
exists, then it probably indicates that the file uses a block which is bad and marked 
as used in the bitmap. If there are no known bad blocks, then a multiple allocation 
of a single block has occurred. In either case, the file should be saved on 
ANOTHER disk (if possible) and then zapped. CHKFSYS should then be run 
again to update the bitmap, after which the saved file may copied back onto the 
disk. 

In general, whenever the bitmap is replaced, CHKFSYS should be mn a second 
time to ensure that the file system is indeed consistent. 

CHKFSYS may also be run after a system crash or power failure which has left 
some files busy. The files may be made unbusy using the chattr command 

chattr s=-b file 

which may then be followed by a CHKFSYS to ensure that no damage to the file 
system has occurred. QNX should be relatively immune to this type of damage. If 
CHKFSYS complains, you may copy the unbusied files to another disk, zap them, 
run CHKFSYS to recover lost blocks, then restore files. For example. 

copy 2:/filel l:/filel 

zap 2:/filel 

ctikfsys 2 
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CHMOD - Change mode of a file 

Description; 

Please refer to the documentation on the CHATTR command. 

See Also: 


CHATTR 

CHGRP 

CHOWN 
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CHOWN - Change owner (member number) of a file 

Syntax: 


chown member jiumber file * 



CHOWN changes the member number of the specified files to member jiumber. 
This number must lie between 0 and 255 inclusive. Member 255 is a group leader. 

Note that this is a shell file which invokes the CHATTR command. 

See Also: 

CHATTR 

CHGRP 
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CLOCK - Display Time and Date On Console 

Syntax; 


dock [options]* 

Options; 

-date - Suppress display of the date. 

-hour - Suppress display of the hour. 

-seconds - Suppress display of the seconds. 

-ampm - Suppress display of the AM or PM. 

-key - Suppress display of keyboard shift status(s). 
a -attr - Select display attributes (hex). 

j(g>«r« o 

clock a=H04 & (white on blue, then inverse) 

Description: 

This command will maintain a real time display of the date and time in the top 
right hand comer of your console display. It will also display the current shift state 
of the CAPS LOCK key, NUM LOCK key and the ALT key. This command 
automatically adjusts its priority to level 15 so that it does not compete with other 
tasks. 

The display attribute bits are defined as follows: 

|eBBBxFFF|xxxxuihb| 

b - enable blink 

h - enable highlight 

i - enable inverse 

u - enable underline 

FFF - foreground colour (if enabled) 

BBB - background colour (if enabled) 
e - enable colour 

x - don’t care 
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This command is included in your "/config/sys.init" file. Should you wish to 
remove the feature, you may edit "/config/sys.init" removing the invocation. The 
command may also be killed at any time by typing the command "slay clock". 

Users with battery backup-up clock/calendar hardware may wish to use the RTC 
command to set the date. This command would be placed in your "/config/sys.init" 

file. 

See Also: 

DATE 

RTC 
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CLRHOUSE - A distributed database and name server 

Syntax: 


clrhouse start [-poll] [p ~poll_sec] &. 
clrhouse poll [n-node] [+me] 
clrhouse locate [n=node] 
clrhouse stop n -node 

Examples: 

clrhouse start & 
clrhouse locate n=l 
clrhouse stop n=4 

Description: 

CLRHOUSE maintains a distributed database for the naming of tasks. Like the 
TIMER task it may be required for some applications. Developers should read the 
technical note mentioned in the SEE ALSO section below. 

STAET 

You may ran CLRHOUSE on up to 3 nodes in the network. Upon starting, each 

task will immediately poll each node in the network for iris list of attached names. 
It will then go into a slow poll mode to refresh this information. This slow poll 
period may be changed using the p -poll_sec options. It defaults to 10 seconds. 
You can suppress slow polling completely by specifying the -poll option. The 
slow polling is not the major means by which the clearinghouse keeps informed of 
task names in the network. Each time a name is attached or detached, the 
clearinghouses are immediately informed. The slow poll is a safety net to handle 
extraordinary error conditions which might cause it to miss an attach or detach 
request from a task. 

POLL 

You can force all the clearinghouses to refresh their infomiation on a node by 
using the POLL option. If you specify a node using the m-node option then the 
clearinghouses will immediately poll that node for it’s list of names. The option 
+me can be used as a short form for n-myjiode. If you do not specify a node then 
all nodes in the network will be quickly polled. This can be used to quickly update 
the clearinghouses after a severe network disturbance (for example, a 
clearinghouse node was disconnected from the network) where you believe their 
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data is not current. It is doubtful that this option will be needed unless you elect 
not to slow poll. 

STOP 

You may kill the clearinghouse by using the SLAY command or the STOP option 
to CLRHOUSE. If you use the stop option you will have to identify which 

clearinghouse to stop using the n=node option. The command 

tsk info 

will list the nodes which are running a clearinghouse. 

LOCATE 

When a node boots over the network it inherits the list of nodes which are running 
a clearinghouse. If you boot from disk you will not know this information. If the 
clearinghouses are slow polling you can wait until you are polled (thus learning 
each clearinghouse one by one) or you can execute the CLRHOUSE command 
with the LOCATE option. This will poll each node requesting it’s list of 
clearinghouse nodes. The first node to satisfy the request will stop the poll and 
update your list. In a stable network this will typically be the first node polled. 
You can force the poll of a specific node only by specifying the m=node option. 

This command would typically be placed in the sys.mit.wn file of a node booting 
from disk. 

See Also: 

NAME functions in the C compiler binder. 

Technical note on "Attaching and Locating Task Names" 
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COMM - Modem communication handler 

Syntax: 


comm [options]* 

Options: 


2i-modem_answer_string- 

b =baud 


B =default_baud 


c=login command 
&=startjieiay 


f=mail_command 

\-modemJnit_string 
1 -log _path 
m-greetingjnessage 
greeting Jile 
n=net_address 
p=pickup_on_ring 

q=quietjime_limit 
r=modem_ok_response - 
s=bbsjcommand 
%-modemjimeout 

-autopar 

+ATI_2400etc 

-CTS_check 

-dropline 

+debug 

+hayes 

+locked_baudrate 

+pass_exception 

-prompt 

-recycle ' - 


Command to force modem to answer. 

Specify a baud rate to try. Multiple 
fo= options can be given from lowest to 
highest. Default is: b=300 b=1200 b=2400. 
Default baud rate to select when the modem 
responds with "CONNECT" and not a bapd rate. 
By default this is 300. 

Command to execute for normal login. 

Delay in seconds after die connect before 
starting the selected login program. The default 
is 2 seconds. 

Command to execute for mail transfer. 
Initialization string for modem. 

Name of directory for log files. 

Initial greeting message to display. 

Initial greeting file to display. 

Mail network address to display on connect. 
Number of rings required for answer. This 
can only be used with the a= option. 

Number of minutes without input before hangup. 
Modem response for command acceptance. 
Command to execute for bulletin board system. 
Modem timeout for response (in 50 msec tics ). 
Supress automatic parity. 

Condition COMM to support this modem. 
Supress checking for CTS modem status. 

Supress dropline function. 

Enable output of debug messages to log file. 
Hayes compatible modem. 

Force locked baudrate to the modem. 

Enable passing of hangup exception. 

Supress "Please type .... " message. 

Supress modem re-initialization after 10 minutes 
of inactivity. 
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-i-verbose - Enable more detailed log messages. 

Examples: 

ontty 3 comm b=1200 +h i=ATS0=0| a=ATA| 

ontty 3 comm c=zarcon b=2400 +h i=ATI| "m=Welcome to zarcon2" 
ontty 3 comm b=300 b=1200 b=2400 

Description: 

The purpose of COMM is to make a QNX system or network accessible by phone 
with a modem. The reason for a special utility is that, unlike a serial link to a 
terminal where the link settings are known, modems tend to operate with variable 
link settings. COMM is able to communicate with the modem to determine these 
settings and to detect when the modem hangs up the phone line so it can remove 
any tasks created during the call. COMM performs the following functions: 

1. Baud rate detection and selection. 

- 300,1200, 2400, etc. 

2. Parity and bits / character detection and selection. 

- even, odd, mark, space, none, 7 bit, 8 bit. 

3. Initial welcome messages, a welcome line and/or a welcome screen. 

4. The command to execute after baud and parity determination (eg: LOGIN). 

5. Removal (killing) of all created tasks upon loss of carrier (hangup). 

If possible, your modem should be configured to provide the CD (carrier detect) 

RS232 signal to the computer so that COMM will be able to detect the modem 
status ( on or off line ). Likewise, the DTR ( data terminal ready ) RS232 signal 
should be connected from the computer to the modem, so that COMM and other 
programs can force a hangup if necessary. Your modem should be programmed to 
force a hangup and reset itself when the computer ’’drops” DTR. For a Hayes 
modem, this command is typically "AT&D2”, but check the manual for your 
modem since this command may vary. 

After COMM has answered the phone and determined the baud rate, COMM will 
wait for the delay specified with the &=start_delay option (default of 2 seconds). 

This delay exists to avoid the burst of noise characters that often occur when two 
modems first connect. After the delay, if a single line message was specified with 
the m ^greeting jnessage option, it will be displayed. COMM will then perform 
various checks depending upon which command line options were specified. If a 
mail handler was specified with the f =mail_command option, COMM will look for 
the protocol characters that indicate an incoming mail packet is arriving and start 
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the specified mail handler. Similarity, if a BBS ( Bulletin Board System ) program 
was named with the $=bbs_command options, a request for the activation of the 
BBS program will be checked for. Note that any commands specified must have 
full paths, for example, the LOGIN default command is "/cmds/Login". 

The input sequences COMM checks for are: 


..<Enter> - Execute the LOGIN, or t=command command. 
<Escape> - Execute the BBS specified with s -bbs_command. 
Mail Protocol - The f -mail command mail handler will be started. 


If COMM determines that a human caller is present, the file specified with the 
M-greeting Jile option will be displayed, after which either the LOGIN, 
c -command or BBS system will be started. If no special commands have been 
specified, LOGIN or the command specified with the c-command option will be 
started as a son task, without any delayed checking for alternatives. 

If the user doesn’t enter any characters for five seconds, COMM will default to 
either the BBS program (if specified), or a command (specified with the 
t-command option ), or LOGIN. 

As part of the baud rate determination, COMM will post an environment variable 
called BAUD which is set equal to the baud rate for the modem connection. This 
variable is useful because many high speed modems operate with the serial link 
between the modem and the computer at a fixed, high speed (usually 9600 or 
19200 baud ) and then use hardware flow control to regulate the flow of data for 
slower connections. Since the true baud rate cannot be determined by the stty 
setting, COMM must post this information as an environment variable so that the 
tasks started by the dial-up user can determine the true transfer rate. As an 
example, QCP file transfers with fast modems benefit from having a packet size of 
16K, rather than 2K. If the program detects that a high baud rate is in effect, it can 
set the "s=16000" option on QCP to provide faster file transfers. 

In addition to setting the baud rate in an environment variable, COMM can also 
keep a log of modem events. The 1 =log_path option can specify either a device 
where modem logs are to go or the name of a directory where log files are to be 
kept. If log_path contains a ’$’ character, it is assumed to be a device and data is 
written directly to that device. If the ’$’ character does not appear in log_path, it is 
assumed to be a directory path, in which case a 7’ and a file name of the form: 

881118 <-» Year, Month and Day 
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is appended to create a filename for the day's log. A directory of the name 
"/commlog" is a good choice, since the COMM_REPORT utility will use this 
directory by default. Note that the logging directory must be created before 
COMM is started. The data written to the log file or device contains various 
messages. For example: 

7:53:55 am [l]$tty22, Connect 2400/MNP 

7:54:00 am [l]$tty22, Executing: Vcmds/login 9 (Login) 

8:04:55 am [l]$ttyl9, Length: 17:47 (Caller Hung Up) 

8:07:43 am [I]$fctyl9, Connect 1200/Noee 

8:07:46 am [l]$ttyl9, Executing: Vcmds/login 9 (Login) 

8:21:16 am [l]$tty22, Length: 27:21 (Call Done) 

8:21:52 am [l]$ttyl9, Length: 14:08 (Call Done) 

8:21:58 am [l]$tty22, Connect 14500/PEP 

8:22:00 am [l]$tty22, Executing: ’/cmds/login’ (Login) 

The LOCATE and WC commands can be used to extract various facts from these 
logs. For example, the command: 

locate 2400 /commlog/881118 ] wc 

could be used to determine the number of 2400 baud calls for that day. 

When the user has finished his call and exited from the program he was running ( 
with LOGOFF, D or a hangup), COMM wil remove the tree of tasks created by 

the user. If desired, COMM can be started with the +pass_exception option so that 
hangup exceptions, rather than kill exceptions, are passed to the user’s tasks on 
hangup. 

For an organized shutdown of COMM, the command: 
slay comm u=4000 

will cause COMM to wait for the current dial-up session to complete before 
terminating itself. This organized shutdown has some very important uses. If a 
dial-up system must be taken down for maintenance, instead of waiting for a 
chance when all the dial-up lines are inactive, or forcibly "evicting” people from 
the system, setting the "shutdown" exception will cause COMM to terminate itself 
on each line as the user on that line hangs up. Ultimately, there will be no COMM 
sessions running and the system will be idle. A shell script which uses the 

slay comm +t 
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option can loop with a timeout until all the active sessions are done before starting 
a backup or other maintenance oriented function. When the backup is done, the 
COMM sessions can be restarted. If COMM is being used with the 
a -modem jmswer_string option, the modems will not answer incoming calls while 
COMM is not present. 

While COMM is operating, it makes itself an administrator task so that it cannot be 
accidentally "killed". If necessary, the SLAY command can be used to forcibly kill 
COMM. Note that any applications the dial-up user is running will also be killed. - 

slay comm u=8000 • 


The q -quiet jime option can be used to limit how long COMM will tolerate a user 
on-line without any input. Assuming q=i5 was specified, after detecting 15 
minutes without user input, COMM would beep the user and display the message: 

Please respond! 

it anotner minute passed witaout user input, COMM would drop DTR, causing the 

modem to hangup and terminate the user session. 

COMM can operate in one of two modes. The first mode is designed explicitly to 
work with Hayes compatible modems and the second is designed to work with 
non-intelligent modems that do not provide connect messages. If your modem is 
Hayes compatible, we recommend using COMM in the Hayes compatible mode. 


Haves Mode 

The +hayes option configures COMM to understand the messages output by a 
Hayes compatible modem. COMM can be configured to initially program the 
Hayes modem to answer incoming calls and then wait for the CONNECT message 
to determine the incoming baud rate. 

You can change the modem initialization string user by COMM with the the i= 
option. The default string is "ATI", but a suggested string could be: 
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ATS0=1 El QO ¥1 XI &C1&02 


L Return to and mode after loss of DTR. 
L BCD indicates carrier detected, 

L Extended status set, 

L English result codes, 

L Result codes sent. 

L Command char echo enabled. 

L Answer after 1 ring. 


With a 2400 baud (or better) modem, these settings can usually be programmed 
into the non-volatile RAM in the modem with the "AT&W" command. If so, you 
■ can set the modem initialization string to "ATZI", causing the modem to program 
itself to the internally saved state. Also, the modem can usually be programmed to 
reset itself to the internally saved settings on loss of carrier, or hangup forced by 
DTR driven low by the computer. 


The modem initialization string supports a number of special characters that are 
processed by COMM rather than being passed to the modem. These characters, 
and their actions, are: 


| - Carriage return 

- Ignored, usually part of a phone number 
~ -1 second delay 

A - Raise DTR 

v - Drop DTR (forces a modem hangup and reset) 
’ -100 millisecond delay 


As the modem initialization string is processed, any characters not in this special 
set are passed through to the modem, unmodified. Using these special characters, 
modem initialization strings that perform many steps can be easily constructed. For 
example: 


¥ ^^a^^ATS0=1| 

would force a hangup of the modem with DTR ( with 3 second delays around each 
change of DTR ) and then program it to answer after the first ring. 

To accept incoming calls your modem need not necessarily be programmed for 
auto-answer. Another alternative is to provide COMM with an answer string. If the 
answer string is provided, the modem can be set to not auto answer ( ATS0=0). 
What will happen is that the modem will emit "RING" statements when an 
incoming call is detected and COMM will detect the "RING" and provide the 
answer string (typically "ATAI" ) to force the modem to answer. This has the 
added advantage that your system will not answer the phone unless it is powered 
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up and the COMM task is ready for the incoming call. We recommend operating 
your modem in this mode. 

If your modem answers with other than "OK ,! to commands, COMM can adapt to 
this with the r-modemykjr espouse command line option. 

We also recommend you default your serial ports to 8 bits, no-parity and one stop 
bit for communication with other QNX systems. 

The following are some typical invocations of COMM for a Hayes modem. 

©ntty $mdm comm +h b=2400 

oetty 19 comm M=/no!/msg +h +1 b=19200 i=ATS0=0| a=ATA| l=/comm!og 


Non-Haves Mode 

COMM can also handle non-intelligent, or non-Hayes mode, modems. When these 
modems answer the phone, COMM will begin to receive the incoming data that the 
remote user is typing. Starting at a previously specified baud rate (default of 2400 
), COMM detects this incoming data and prints the message: 

Please enter two periods (. 0 ) and press <Enfer> 

If the baud rate is incorrect, any character typed by the user will generate a 
communication error causing COMM to switch its baud rate and redisplay the 
above message. The periods (..) and carriage return must be typed in order without 
any mix of other characters. Every three characters entered will redisplay the 
above message. Often, the sequence "ab.." seems to be most efective at generating 
enough exceptions for COMM to be able to determine the line settings. Space 
parity is treated as 8 bit, no parity by COMM. 

After the caller has hung up, the baud rate is then switched back to the highest rate 
and the process starts over, waiting for the next call. 

If your non-hayes modem has a feature to print a string when a call arrives, you 
should TRY to disable it since this may confuse COMM working in the non-hayes 
mode. This is especially true if the string contains either a carriage return or a 
period. You should also try to disable ECHO from the modem and any status 
messages. 

This is a typical invocation of COMM for a non-intelligent modem. 

oetty 22 comm M=/nol/msg b=300 b=1200 b=2400 f=/commlog 
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Recognizing the fact that COMM is a utility that many people would like to 

modify for custom applications, the source for COMM is available on the QNX 
Update System and is also shipped as a sample C program with the QNX C 
compiler. There are also a number of technical notes downloadable from the 
update system that detail how to configure various modems for use with QNX and 

COMM. 

See Also: 

LOGIN 
LOGOFF 
STTY , 
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COPY - Copy files 

Syntax: 

copy sourceJile destinationJile [options]* 

OR 

copy file* directory [options]* 

Options: 

-date - Don’t copy the date. 

+pause - Pause before copying (to change diskettes). 

4verbose - Display filenames as they are being copied. 

Examples: 

copy *.c /cjsource - Copy all c files to the directory 
/c_source. 

cp testx $lpt - Copy file test.c to the line printer. 

Description: 

Copy is now identical in operation to the CP command. Please refer to the CP 
utility for details on it’s operation. 

See Also; 

BACKUP 

CHATTR 

CP 
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CP - Copy files 

Syntax; 


cp sourceJile destination file [options]* 

° R 

cp file* directory [options]* 

Options: 

“date - Don’t copy the date. 

-fpause - Pause before copying (to change diskettes). 

-f verbose - Display filenames as they are being copied. 

+newest - If the destination file is newer than the source, then do 
not copy; keep the newest of the two. 

Examples: 

cp *.c /csource - Copy all c files to the directory 
/c_source. 

cp teste $Jpt - Copy file test.c to the line printer. 

Description: 

The first form CP will copy a source file to a destination file. If no destination file 
is given, the standard output is used. If no source file is given, the standard input is 
used. 

The second form of CP will copy multiple source files to a destination directory. 
This provides a convenient method of moving files in one simple operation. The 
SHELL special characters *, ?, and [...] are useful for selecting the set of files to be 
copied. If the error 

LINE TOO LONG 

is displayed, you will have to restrict the number of files copied and issue two or 
more commands. 

cp *.[co] dir --> cp *.c dir 

cp *.o dir 
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The following two commands achieve die same effect using the two forms 

cp 2:/doc/report l:/docJbackup/report 
cp 2:/doc/report l:/docJbackup 

A dash (-) may be used to force the source input from standard input, or to force 
output to standard output 

CP copies as much of the source file as it can into memory, then flushes the 
memory buffer to the destination file. This is repeated until the entire file is copied. 

The +p option allows the user to change diskettes (in a floppy only system) before 
actually transferring the files (so that die destination diskette can be inserted into 
drive 1 for example, where the commands disk which contains the CP command 
usually resides). CP will prompt the user for a carriage return before initiating the 
copy operation when +p is specified. 

The «d option will use todays date for the destination file. The default is to copy 
the date from the source file to the destination file. The default form of the CP 
command requires that the destination file have "modify" permission, since the 
date of the destination file is being modified. If modify permission is missing, you 
will have to use the -date option. 

See Also: 

BACKUP 

CHATTR 
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CRON - Schedule commands in background 

Syntax: 


cron [-Sogfile] [l=logfile] [t=tablefile] &+ 

Options: 

-logfile - Do not append status information to 
any log file. 

1 =logflle - Use die indicated log file in place of 

the default logfile /config/cronlog. 

' t-tablefile - Use the indicated table file in place of 
the default table file /config/crontab. 

Examples: 

timer & 

cron -I t=/etc/crontab &+ 

Description: 

The CRON command provides a convenient method for executing commands at 
specific times without operator intervention. It requires that the timer administrator 
be running in background. 

Cron is a resident program that uses a list of times and program names contained in 
the file /config/crontab. This file has a single line entry for each program to be 
executed that contains the following six fields: 

1. The minute in the hour (0-59). 

2. The hour of the day (24 hour clock). 

3. The day of the month (1-31). 

4. The month of the year (142) OR 

(a 3 letter monthname). 

5. The day of the week (0-6 where 0 is Sunday) OR 

(a 3 Setter day name). 

6. A command to be executed in the background 
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Any of the time fields may have: 


a single value 3 exact 

an upper and lower boundary 10-15 range 

a series of values 2,5,11,33 list 

a "*" to mean all values * all 


Each element of a list may of course be a range. The following examples illustrate 
some typical cron table lines. The indented comment text is NOT part of the cron 
table file. 

15 * * * 1-5 who »/etc/wholog 

OR 

15 * * * mon-fri who »/etc/whoiog 

At 15 minutes after the hour on Monday 
thru Friday append the output of the who 

command to the file /etc/wholog. 


01*** /cmds/diskuse 

At 1 AM each day run the shell command 
file diskuse. 


0 41,15 * * payrolljstartup 

At 4 AM on the first and the fifteenth 
run the program payroll_startup. 


55 7 * * 1,2,3,4,5 ontty 3 comm 

At 7:55 AM Monday thru Friday start the 
dialup access routine. This assumes a reboot 
every morning or multiple COMM programs will 
start to stack up. 

0 01 jan * mail s % users cnewyearmsg 

On the first of january every year send mail 
to everyone in the file users. 
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The command which is scheduled to run will be run in background. Its standard 
input will be the device $null and its standard output and error will point to the 
console on which CRON was run in background. 

Each time the cron table is read by CRON, or CRON schedules a program to run, a 
status message is appended to the cron logfile unless the -logfile option was 
specified. It is possible to run a command from CRON which prints then deletes 
this file once a week. 

If a time in the cron table has already passed when CRON is started, that command 
will not be run. CRON reads the cron table file once (within 1 minute) when it is 
started. If you modify the table file you may force CRON to reread this file by 
setting a break exception on CRON. For example. 

slay cron +break 
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CRYPT - Encrypt/Decrypt files 

Syntax: 

crypt [ key] <inputjile >outputJile 

Options: 

key - Encryption key to use. 

input Jile - Source file to encrypt. 

output Jile - File to place encrypted output. 

Examples: 

crypt secret, ctable >table.x 

ws "crypt qwerty <@ >@.x" p=*.c - Encrypt all C files 

in current directory 

Description: 

CRYPT reads from the standard input and writes an encrypted version of the data 

to the standard output. The KEY selects a particular transformation of the data. If 
no key is specified, CRYPT will prompt for a key from the terminal (without 
echoing it). CRYPT encrypts and decrypts with the same key. After executing 
these two commands 

crypt abc <filel >fi!e2 

crypt abc <file2 >file3 

file3 will be identical to filel. 

CRYPT implements a one rotor machine with a 512 byte rotor. Such an encryp¬ 
tion scheme can be broken, however, the amount of work required is likely to be 
large and not generally known. 

Since the encryption relies heavily on the key, small keys (3 characters or so) 
should be avoided. 

CRYPT flushes all input to prevent users from recalling command lines in order to 
redisplay the key. 
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DATE - Display or set date and time 

Syntax; 

date [day [month [year [hour [min [sec]]]]]] [amlpm] 

Options: 

day - 1-32 

month - 1-12 or jan-dec 
year - 80-99 or 1980-99 
hour - 1-12 or 0-23 
min - 0-59 

sec - 0-59 

am - (used with 12 hour time) 

pm - (used with 12 hour time) 

Examples: 

date 

date 22 2 82 

date 16 july 1982 4 30 pm 

Description: 

If no arguments are given, the DATE command allows the user to display the date 
and time on his terminal. When changing the date, day is entered first followed 
optionally by month and year. The current time can also be set by following the 
date with the hour, minute, and second. 24 hour or 12 hour time (am or pm) can be 
used. All arguments must be separated by spaces. Any missing arguments will 
default to the current value. 

For details of setting the QNX date from a battery backed-up clock/calendar, see 
the RTC command. 

See Also: 

CLOCK RTC 
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DCHECK - Check a disk for bad blocks 

Syntax: 

dcheck drive [options]* 

Options: 

b=num_hlks - Number of blocks (in decimal) to check 
(default: all blocks). 

4-mark - Mark bad blocks as used in the bitmap. 

-verbose - Don’t display progress information. 

4 -verbose - Display every bad block on the disk. 

-pause - Don’t wait for a disk to be inserted. 
f=first_blk - Start the check at this block number. 

Examples: 

dcheck 2 4-ra - Check all blocks on disk 2 and 
mark bad blocks in the bitmap 
dcheck 1 b=640 - Check first 640 blocks on disk 1 
dcheck [3]1 - Check all blocks on disk 1 of node 3 

Description: 

DCHECK allows the user to verify that a disk has been formatted properly. The 
utility will do this by attempting to read every block on the disk. Any blocks which 
cannot be read will be displayed on the standard output (which may be redirected 
to a file). Bad block numbers are displayed in hex. A summary of die number of 
bad blocks will always be printed on the terminal. 

If the number of blocks to check is not specified, then DCHECK will obtain the 
correct number from the file system and check ALL blocks on that disk. 

DCHECK can be used to check any formatted disk, including disks which contain 
files. These files will not be damaged. If the disk has been initialized using 
DINIT, the 4-mark option should be used to remove any bad blocks from the disk 
allocation bitmap. This is especially tme for hard disks. 

IMPORTANT: DCHECK with the the -f mark option should only be used when 
the system is idle. There should be NO open files when DCHECK is running. 


[DCHECK] 


Utilities 



©CHECK 


When mark is specified, DCHECK will attempt to read the file /bad_Mks from 
that disk. If found, DCHECK will read in the file which contains a list of all known 

bad blocks, in sorted order. When DCHECK finishes, it will re-create the file 
/bad_blks, after it has updated the bitmap. DCHECK will only add to this file, 
allowing transient or marginal disk blocks to be detected, and avoided, by 
repeatedly calling DCHECK: 

dcheck 3 +mark 
dcheck 3 +mark 
etc. 

The /bad_blks file is also recognized by the CHKFSYS utility. 

DCHECK may be used to check a disk on another node. The disk may be 
indicated explicitly via a [node] prefix or implicitly by specifying a remdisk which 
you have mounted. 

The file created by redirecting the output of DCHECK may be used as a data file 
for the CHKFSYS command. This allows you to detect which file (if any) 
contains bad blocks. 

dcheck 3 >bad_b!ocks 
chkfsys 3 b=bad_blocks 


See Also: 

CHKFSYS 

DINIT 

FDFORMAT 

MOUNT 
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OCOPY - Copy entire disk to a second disk 

Syntax; 

dcopy [source [destination]] [options]* 

Options: 


source 
destination 
+hard 
-verify 
k -size 


b-nblocks 
so -offset 
d®=offset 
-{-repeat 
-pause 


Source drive (default: 1). 

Destination drive (default: 2). 

Allow copying to a hard disk. 

Don’t verify after copying. 

Size of disk to copy in Kbytes 
(default: ALL blocks). 

Size of disk to copy in blocks. 

Offset on source disk in diocks. 

Offset on destination disk in blocks. 
Continue copying until user types BREAK. 
Don’t pause for non-floppy disks. 


Examples: 


dcopy 1 2 - Copy all of disk 1 to disk 2. 

dcopy 1 1 - Copy a disk using a single drive. 

dcopy -v +r - Make multiple copies of disk 1 

without verifying. 

dcopy 2 1 b=160 - Copy disk 2 to 1. Only copy 

160Kbytes. 

dcopy 3 1 so=640 k=320 

- Copy the second 320Kbytes of 
drive 3 to drive 1. 

dcopy 1 3 b=640 do=640 +h 

- Restore the second 320Kbytes 
of drive 3 from drive 1. 

dcopy [4]1 [6]1 - Copy disk 1 on node 4 to 

disk 1 on node 6. 


Description: 
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DCOPY allows the user to make an exact copy of the diskette in the source drive' 

(default 1) onto the diskette in the destination drive (default 2). 

CAUTION: This utility is NOT meant for copying files. It is meant for copying 
exact disk images. Use CP, or BACKUP for copying files. 

DCHECK will prompt the user to load the diskettes into the appropriate drive and 
type CR when ready. DCOPY will read as many blocks as it can from the source 
drive into memory, then write them onto the second drive. This will be repeated 
until the entire diskette has been copied. 

Normally the data on the destination drive will be read back and compared with the 
memory buffer to ensure that the data has been copied correctly. This can be 
suppressed (to speed up disk copying) with the -v option. 

The b= and k= options allows the user to make copies of only a portion of a disk. 
The + r option allows multiple disk copies to be made without the need to key in 
the DCOPY command every time. The so= option permits the first part of the 
source disk to be ignored. Offset is specified in blocks. The do= option allows an 
offset to be specified on the destination drive. 

Note that a blank floppy diskette must be formatted before it can be copied to. 

Although DCOPY is normally used to copy floppy diskettes, a ramdisk or a hard 
disk can also be copied to/from floppies. TTie k=, so=, and do= options allow an 
entire Hard disk to be copied onto several floppy diskettes. Command files 
consisting of several DCOPY commands could be built to make this more 
convenient. The -p option can be used to avoid the prompt message which results 
when one of the disks is not a floppy. 

For your protection, copying to a hard disk is not allowed unless you specify the 
+hard option. This should protect against any typing errors. 

You may DCOPY to disks on different machines. This may may be indicated 
explicitly via a [node] prefix or implicitly by specifying a remdisk which you have 
mounted. 

See Also: 

BACKUP 

FDFORMAT 

MOUNT 
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DDUMP - Dump the contents of a disk block 

Syntax: 

ddump drive block [-verbose] 

Options: 

drive - Disk drive number (1..F). 

block - Disk block number in hexadecimal (1..?). 

-verbose - Don’t display as ASCII characters 

Examples: 

ddump 3 1 - Dump block 1 of disk 3 

ddump 1 10A -v - Dump block 10A (hex) of disk 1 
ddump [4]3 2 - Dump block 2 of disk 3 on node 4 

Description: 

DDUMP will display the contents of a disk block 16 hexadecimal bytes per line, 
with the ASCII equivalent (if printable) displayed to the right of the line. If the 
ASCII character is not printable, it is replaced with a dot (.). 

The disk block is specified as a hexadecimal number. 

Subsequent disk blocks can be displayed by typing CR for each new block. Any 
other typed character will terminate DDUMP. 

DDUMP may be used to dump a disk on another node. The disk may be indicated 
explicitly via a [node] prefix or implicitly by specifying a remdisk which you have 
mounted. 

See Also: 

MOUNT 

NACC 
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DEBUG - Invoke the system debugger 

Syntax: 


debug [command line ] 

Examples: 

debug - Drop into the debugger, 

debug test argl >$Jpt - Debug the program ’’test" 

Description: 

If you wish to do source level debugging please refer to QDB in the C compiler 
manual. This is a low level debugger suitable for debugging interrupt handlers. 

DEBUG allows the system debugger to be used, provided that it has been first 
mounted into the system. This should only be done once. 

mount debug 

The debugger is an absolute (hex) debugger which allows breakpoints to be set in 

user programs, memory to be displayed and edited, code to be disassembled, and 

I/O ports to be examined. 

The debugger can only be invoked from the console. The debugger should never 
be used in a multi-user environment. It disables interrupts and freezes the entire 
system. It may be used to debug application programs as well as interrupt routines. 

With no arguments, DEBUG will be entered with a 4K memory buffer at its 
disposal. If a command line follows the keyword debug, then that command will 
be loaded into memory before the debugger is called. In this case, the debugger 
will have its default code and data segments initialized to those of the command 
being debugged. 

Breakpoints can be set on functions whose addresses have been determined from 
the map which can be generated by the linker. 

cc test m= 0 map. 

cc x=ofi!e§ m= e map» 
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Similarly, the addresses of memory variables can be determined from the linker 
map and displayed in the debugger. 


The debugger does not support line editing. If you make a typing mistake you may 
cancel the entire line by typing a Ctrl c. When entering addresses, etc. all data is 
assumed to be hexadecimal. Only the last 4 digits are valid (2 for byte data) so 


typing mistakes can be corrected by i 
last 4 digits are the ones you want. 


type the 


• mich that the. 


Ib341d44 results in ld44 


If you type a simple DEBUG, perhaps to examine an I/O port, you may return back 
to the shell by typing the g command. If you debug a command, then your default 
code (@ @) and data (@) segment will be set up to point to your program. Note 
that the CS register displayed when you first enter debug will be pointing into the 
shared library, NOT your program. All breakpoints will be placed in your real code 
segment which the shared library will return to when you resume via the g 
command. 


A WORD OF WARNING. If your program allocates considerable memory via the 
ALLOC, CALLOC, MALLOC or OPEN routines, then QNX may relocate your 
data segment without updating the default data segment memorized by the 
debugger when your program began execution. As a rule of thumb, the stack seg¬ 
ment (ss:) will be your real data segment which should agree with the value printed 
for ds= when you type ?. If not, you may change your default data segment using 
the @ command. Note that the default data segment is ONLY used for displaying, 
examining and changing memory. Changing it does not affect the data segment of 
your program. It is there to save you from having to type in a segment prefix. 

When debugging multiple tasks, you may wish to change your default code and 
data segment many times for convenience. 
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Debug Command Summary 

b address Set breakpoint at address 

b seg'.address 

b r Set breakpoint at return from C function 

b Display breakpoints 


c start finish destination Copy memory 

c seg'.start finish segidest 

d address Display memory. CR ends display 

d seg'.address and SPACE displays another line 

D address Disassemble memory 

D seg'.address 


e address Edit Memory 

e seg'.address 

EDIT commands 


hex number 
’c 

CR 

SPACE 


'.data 

;data 

r 

R 

/ 


Changes contents of memory 

Changes to ascii character c 

Leaves edit 

Goes to next byte 

Redisplays this byte 

Displays previous address 

Displays 8 bit 10 port 

Displays 16 bit 10 port 

Output to 8 bit 10 port 

Output to 16 bit 10 port 

Goes to short relative address 

Goes to long (16 bit) relative address 

Goes to the address found in memory 


f seg'.startfinish data Fill memory with data 

f start finish data 

g address Go to address (begin execution) 

g seg'.address 

g Continue execution (or exit debug) 


Utilities 


[DEBUG] 



DEBUG 


1 start finish data 
1 segistart finish data 

r reg 

rregdata 

s 

s count 

t n 

T n 

u address 

u 

¥ 

? 

@ segment 

@ @ segment 

@ i mask 

@ p 

@ s data 


Continue execution, but reset a breakpoint 
at the same address 


Locate data in a range. Up 
to 8 bytes may be searched for. 

Examine contents of register 

reg : ax bx cx dx si di bp es ds cs ss 

Change contents of register 

Single step from last instruction. You may 
type the space bar to step through your 
code, one instruction at a time. 

Execute count instructions or until 
next breakpoint 

Display last n C sfcackframes 

Display last n instructions executed 
while single stepping 

Unbreak (remove break) at this address 

Remove all breakpoints 

Trap all Protected-mode interrupts. 

Display registers 

Define default data segment 
used by d e f c commands 

Define default code segment 
used by D b u s g commands 

Define interrupt mask which will be 
restored when program resumes. 

Change stack pointer 

Change stack segment 
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See Also: 

LINK 

MOUNT 

QDB Symbolic Debugger 
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- Define id of global name server 



def server node taskjd [+local] 



node - Node number where the server task resides. 
taskjd - Task-id of the server task. 

+local - Only change server on local node. 

Examples: 

def server 3 1 - make TASK_ADMIN on node 3 a 

global name server. 



The DEF_SERVER command defines the node and taskjd of a global name 
server task. This may be a user defined task or a TASK ADMINISTRATOR on 
any node. Global names are used by administrator tasks which provide network 
wide services. The SPOOLER is an example of such a task. This command may 
be executed on any machine and all machines in the network will be updated with 
the information. 

DEFJSERVER will attempt to update the global name server information on every 
node in the network, unless the +locaI option is used. If it is, then only your node 
will change its value for global name server. 

This command is only useful with the networking version of QNX. 

The default name server in a QNX network is task-id 0001 on node 1. Most users 
will NOT need to change this. 

See Also: 

CLRHOUSE 

SPOOL 

TSK 
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DEFPIPE - Define temp files for pipes 

Syntax: 


defpipe path 

• This is a local shell command ® 



The DEFPIPE command allows you to change the pathname where temporary pipe 
files are placed. 

defpipe myjpipe 

The default is 

defpipe /tmp/..#n#$ 
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DIFF - Difference between two files 

Syntax: 

diff file! file2 [options]* 

Options: 

4-editor - Creates a script of line edit commands 
which can convert file] into file2. 

(see the LED command) 

4-matching - Produces a script of matching lines in 
the two files rather than the difference. 

+raw - v^auscb ct ^nui ciCtCi oy unai duid 

comparison of the two files. A file 
match or mismatch statement will be 
issued if necessary indicating the 
characters (and character number) where 
the mismatch occurred. The -v option 
may not be used with 4-raw. This option 
must be used when comparing binary files 
such as commands. 

-blanks ■ - Causes multiple blanks or white 
characters to be ignored in line 
comparisons. 

-case - Causes case distinction to be ignored. 

+heading - Displays the names of the files being 

compared. This may be useful without any 
other option or the +ra and +r options. 

-null - Causes null lines to be ignored. This 

option should not be used with the +e 
or +r options. 
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t-resync - Changes the minimum number of lines 
required to match before the two files 
resynchronize. The default is two, the 
new value must between one and one 
hundred. 

s=mcix_diff - Changes the maximum number of lines 
the files may differ by at any time before 
being declared incomparable. The default 
is one hundred. 

t ^string - Define terminator string to print between 

sections of text. 

-verbose - Disables the "The two files compared 
equal" message. 

-write - Suppress "w" command in LED script 
created by the +e option. 

Examples: 

diff versionl version2 

- Creates a meaningful script of differences between the 

files. 

diff old new +e >chgs 

- Compares the original file to the new version creating 
changes which will convert the old file into the new 
version. To recreate the new version use: 

led old ccfags 

diff Corel core2 +r 

- Allows text or non-text files to be compared character by 
character. 

diff filel ftle2 +m 

- Displays the similar text segments between the given 

files. 

Description: 
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DIFF compares two files line by line searching for differences between them. It 
can illustrate these differences by producing a meaningful script of edit-like 
commands. The commands are of the form: 

rangel C range2 
[< fileljext]* 

[> fileljext]* 

Where: 

rangel is line number range in file 1 
range2 is line number range in file 2 
C is the LED command append, delete or change 
< indicates a line of text affected in filel 
> indicates a line of text affected in file2 

In many situations, several versions of a file may exist. You may reduce file space 
requirements by saving diff files rather than multiple similar copies. When you 
update a file, DIFF +e can summarize the session as a series of line editor 
commands. Typically a file containing the LED commands will be much smaller 
than the updated version of an original file. Thus, if several versions of a file are 
necessary, a great deal of disk space can be saved by keeping one original file and 
several difference files. 

If similarities between the files are required, the +m option will display the files 
corresponding line numbers followed by similar lines of text. 

When it is necessary to compare files character by character (binary files), instead 
of as lines of text, use the +r option. The output will state if the files are equal. If 
not, the character position and corresponding characters will be given. 

See Also: 

LED 

LOCATE 


[DIFF] 
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DINIT • Diskette Initialization 


Syntax: 

dinit drive [+hard] [k -size] [p=lprefix] [+suppress] [-pause] 

Options: 

+hard - Required if the disk is a hard disk, 
k -size - Size of diskette in Kbytes, 
p =lprefix - Name to give the root of the file system on that 
disk (default is 7") 

-pause - Don’t pause for diskette to be loaded. 

+suppress - Suppress the writing of the root directory. 

Examples: 

dinit 3 +hard 
dipit 1 

dinit 1 p=/user 
dinit 5 -p 
dinit [3]1 

Description: 

DINIT wiE initialize a formatted diskette so that it may be used in the QNX file 
system environment. The default values are determined from the current configura¬ 
tion of the specified drive. This configuration can be changed with the MOUNT 
command. 

The prefix (if specified) is the name of the "root" of the file structure on that drive. 
The default prefix is which allows any directory names to be placed at the 
highest directory level on that diskette (eg. the drive could contain the directories 
/cmds, /lib, /expl, etc...). If a diskette is known only to contain one directory at the 
highest level (eg. /user), then this prefix can be given. The prefix must start with a 
slash (/). In practice, this option is rarely used. 


Initialize a hard disk in drive 3. 
Initialize a disk in drive 1. 

Initialize disk in drive 1 to 
have a root name of "/user". 
Initialize disk in drive 5 without 
pausing (perhaps a ramdisk). 
Initialize disk in drive 1 on node 3. 
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DINIT 


A diskette which is given a prefix other than 7" cannot be accessed without giving 
the exact name of the disk. A user could name a diskette with a unique name 
known only to himself which would prevent other users from looking at the files 
on that diskette. 

The -p option can be used to bypass the prompting for a diskette to be loaded. 

In the case of a hard disk the DINIT should be followed by a DCHECK to remove 
any bad blocks from the disk allocation bitmap. 

dinit 3 +hard 
dcheck 3 +mark 

The +hard option is required if the disk is not a floppy or ramdisk. This option is 
there to protect you against accidental typing errors which might attempt to DINIT 
your hard disk. 

The +suppress option is only used after a disaster which has destroyed the first 
few blocks of your disk. Please read the technical note on "Recovering Your Hard 
Disk". 

The k= option will rarely be required. It may be used to create a bitmap which is 
smaller than the physical disk. This will prevent QNX from touching blocks at the 
end of the disk. 

dinit 1 k=252 - 28 tracks * 2 heads * 9 sectors 

reserve inner 12 tracks 

DINIT may be used to initialize a disk on another node. The disk may be indicated 
explicitly via a [node] prefix or implicitly by specifying a remdisk which you have 
mounted. 

See Also: 

DCHECK MKDIR 

FDFORMAT MOUNT 


[DINIT] 
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DIR - Display directory tree 

Syntax: 

dir [directory] [options]* 

Options: 

+count - Display a count of the number of files in each directory. 

-files - List only directories, not files. 

-t-modified - Display any directories that contain modified files with the 
enhanced video attribute ( or with a preceding character 
for output devices without enhanced mode ). The only files 
that will be listed while this option is in effect will be those 
that are modified. Thus, a command like 

dir 3:1 +m 

will create a display of the complete directory tree and only 
those files that have been modified since the last backup will 
appear within the tree. 

Do not sort the output. 

Maximum number of sub directories allowed in a single 
directory. The program will halt if there are too many. The 
default is 60. 

Sets the maximum number of files that will be printed within 
a single directory. The error message "too many files" will 
appear if more are present. The default is 650. 

Limit the depth of the directory tree. Default is 9999. 

Specify a pattern to select which files are listed. This pattern 
match facility applies only to file names and not to directory 
names and is applied only to files that make it through the 
flag settings, such as the -{-modified flag. The ’ A ’ character 
can be used to negate the pattern match. 

Amount of memory (bytes) used to store directory and file 
names while processing. The default is 25 Kbytes. 

This option can be used to manually specify the output 
width. The default width is 80. This is useful when printing 
a directory with -f files to a 132 column printer. 

Examples: 


-sort 

d =max_dirs 
f=maxjiles 
1 =levels 

p=[ A ]pattern - 

m=memory 

w =lim width - 
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DIR 


dir 

dir 3:/ w=132 >$Ipt 

dir +m +c 1=2 

Description: 

This utility displays a hierarchical view of the directory system. If no directory is 

named5 the directory tree from the current directory down is displayed. 

The output of this command uses the tcap library for the line drawing characters 
and can thus be used to print directory trees on the printer or attached terminals as 
well as on the screen. 

See Also: 

CD LS 

FILES PWD 


[DIR] 
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DMARK - Mark bad blocks on a disk 

Syntax: 

mark drive [cylinder,head]* 

Options: 

drive - Which QNX drive is to be marked. 

cylinder - Which Cylinder is bad. 

Values range from 0 to T-1. 
head - Which head, or platter is bad. 

Values range from 0 to H-l. 

Examples: 

dmark 3 40,4 250,2 500,0 - mark track 40, head 4 

and track 250, head 2 
and track 500, head 0 

dmark 3 20,1 >3:/bad_blks 

Description: 

If your hard disk was shipped with a sheet of paper containing a list of bad tracks, 
then you may use the DMARK command to explicitly mark the blocks on these 
tracks as un-usable. 

DMARK will display a list of QNX block numbers on the screen corresponding to 
the bad blocks. This may be re-directed into a file, which can be used by 
CHKFSYS to update the bitmap on that disk. 

If DMARK is used immediately after using DINIT on a new hard disk, you could 
direct the output into the file /bad_blks on that disk. The DCHECK and CHKFSYS 
utilities will then maintain that file as new bad blocks are discovered. 

The DMARK command takes a list of cylinders and heads. Each pair is separated 
by a space, with the cylinder and head separated by a comma. 

Note that even if only a single block is bad, the entire track is sacrificed. This is 
because interleaving of sectors on the disk locates blocks in different places, 
beyond our control. 
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DMARK 


DMARK is best used in conjunction with DCHECK, which will find any blocks 
which have failed since the disk was originally manufactured. 

See Also: 

CHKFSYS 

DCHECK 

DINIT 

FDFORMAT 

MOUNT 


[DMARK] 
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DOPEN - Display open devices 

Syntax: 

dopen [node] 

Options: 

node - The node whose devices you wish to query. 

The default is your local node. 

Return Value: 

Number of devices open 
-1 on a critical error. 

Description: 

DOPEN will print out the names of any tasks which have a device open for read. 
It does not list tasks which have a device open for write only. This command is 
frequently used to determine who has the modem port open. 

DOPEN only lists the devices open on one node at a time. It defaults to your 
current node. You can specify a node using the node option. 

dopen 4 

See Also: 

FOPEN 
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OREL - Release Directory 

Syntax: 

drel directory 

Examples: 

drel /test 

drel /user/bill/catl 

drel 2:/user 
drel [2]3:/user 

Description: 

DREL will remove a directory from the disk. Only empty directories can be 

released. If the DREL command verifies that the directory is empty, then the space 
used by the directory will be reclaimed. 

If a directory is to be removed which is at the top level (root), it is usually 
necessary to specify the correct drive prefix as in the last two examples. 

See Also: 

FREE 

RM 

RMDIR 


[DREL] 
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DUMP - Dump the contents of a file in hexadecimal format 

Syntax: 


dump file [start_ojfset [end_ojfset]] 

Options: 


start ^offset - First byte to display (decimal) 

default: 0. 

end_offset - Last byte to display (decimal) 
default: last byte of the file. 


Examples: 

dump test.o - Dump an entire file, 

dump core 0 120 - Dump the first 121 bytes of "core", 

dump $tty3 - Dump data from $tty3 (At least 80 chars 

need to be sent before being displayed). 

Description: 

DUMP will display the exact contents of a file, 16 bytes per line (hexadecimal), 
with the ASCII equivalent (if printable) displayed to the right of die line. If the 
ASCII character is non-printable, it is replaced with a dot (.). 

DUMP is useful for displaying non-text files such as object files and core files. 

The start and end offsets are specified as decimal numbers. 

See Also: 

p 

SPATCH 
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DUMP_IBM - Make a hardcopy of Graphics Screen 

Syntax: 

dumpibm [options]* 

Options: 

devicejiame - Name of printer to use if not $lpt. 

+highjes - dump high resolution screen (640 x 480) 

+m ediumjres - dump medium resolution screen 

Examples: 

dump_ibm - Make hardcopy of graphics screen. 

dump_ibm [7]$Ipt - Make hardcopy on node 7’s printer. 

Description: 

This command will make a hardcopy of the IBM colour graphics screen onto an 
IBM compatible graphics printer. 

It is typically called from other programs (such as BAR) to print the graphics 
screen since issuing the command by hand would alter the display. 

See Also: 

BAR 

MOUNT 
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EC - Execute a shell file 

Syntax: 

ec shellJUejtame 

• This is a local shell command « 

Description: 

The EC command causes the shell to temporarily take its input from the indicated 
file. Since the execution of commands in the file is performed by the current shell, 
it is possible to execute commands like CD, PATH, PRI, PROMPTT etc..., which 
affect the environment of the shell which executes them. 

This is especially useful in the password file where you will often see a line such 
as 

ec userinit 

EC commands cannot be nested. 

See Also: 
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ECHO - Echo arguments to standard output 

Syntax: 


echo [ arguments ]* 

Examples: 

echo Hello world!!! 

echo abc >$tty3 

Description: 

ECHO will echo its arguments to the terminal. ECHO is used within command 
files to display progress information. The last argument will be followed by a 

-TC /I* - jCU_ 

wtii i idge-ieium/ ime-ieea. 

Unlike TYPE and STYPE, the output of ECHO can be redirected since it is a 
executable program and not a SHELL command. 

See Also: 

STYPE 

TYPE 


[ECHO] 
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EO - Execute On 


Syntax: 

eo [file] "command '’ [options]* 

Options: 

+concat - Each line in the input file is concatenated 

and separated by a space. The indicated command 
is called only once with multiple arguments 
rather than many times with a single argument 
-error - Don’t stop if a command returns back a non-zero 

status. This includes a command stopped via break. 
Q=offset - Skip this many characters at beginning 

of each line before executing, 
p ^pattern - Skip any line which does not match 

this pattern (before applying o=). 

+repeat - This is only used in conjunction with the +concat 

option. If during concatenation of the input 
lines into multiple arguments the maximum line 
size of 256 characters is exceeded, then the 
command will be executed with as many items on 
the line which will fit. This process is repeated 
until there are no input lines left or line 
greater than 256 characters is read. 

+verbose - Display commands as they are being executed, 
dc =del_char - This character when present in command 

will delete the last character of the current, 
pathname (default is a backquote) 
pc =path_char - This character when present in command 
will be replaced by the current pathname. 

If omitted, then the argument will be 
appended after the command. Note that the 
pathjchar is consumed by the first argument 
when used with the +concat option. 

(default is an at-sign @) 

Examples: 

eo my files "list -b" +c 
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- List all files named in my_files 

eo cfiles "ed @" +v 

- Edit all files named in cfiles 
files -v p=*.o | eo "frel" +c +r 

- Release all files ending ".o" 

Description: 

EO, like WS, is a utility which increases the power of existing QNX commands. It • 
takes a command and a file containing a list of filenames with one filename per 
line. The command will be executed once for each line in the specified file, with 
the line being appended as an argument to the command. Given a set of filenames, 
EO allows a convenient mechanism of executing a command across all those files. 
The file list will typically be generated using the editor or from the output of the 
FILES command. 

files >cfiles p=*.c -v 

eo cfiles ’’crypt key <@ >@.z’’ 

If thzfile of filenames is omitted, then me filenames will be read from the standard 
input. This allows EO to be used as a filter in a pipe. The above command could 
be shortened to a single step as 

files p=*.c -v | eo "crypt key <@ >@.z" 

Some commands are capable of accepting multiple arguments. In these cases it is 
more efficient (and sometimes necessary) to execute the command once with many 
arguments rather than many times with one argument. The +concat option will 
take each input line and concatenate them together, separated by spaces. The 
command will then only be executed once. For example 

eo my files "size" +c 

The +repeat option handles the case where the number of input lines when 
concatenated will exceed the maximum line size of 512. In this case the command 
will be executed with as many items on the line which will fit. This process is 
repeated until there are no input lines left, or a line greater than 512 characters is 
read. 
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EXPL - Explain 

Syntax: 

expl [command [ subcommand ]* ] [options]* 

Options: 


in -menu 
p -lines 

Examples: 


- Force QNX display character set and 
escape sequences to be used. 

- Go immediately to indicated menu item. 

- Pause after this many lines, 
default is 24. p=0 disables pausing. 


exp! inform m=B 

expl led command summary p=0 >$lpt 


Description: 


The EXPL command provides a convenient method of indexing into the directory 
of files found under the directory "/expl". 

The explain files provide detailed information about commands. If the required 
explain file cannot be found, but a file called "index" is present in "/expl", EXPL 
will ask if an explain index is wanted. If the user responds with ’y\ then the file 
/expl/index is printed (if it exists). Typing "expl index" on the command line will 
also print this file. 

The disk containing the directory "/expl" must be inserted into one of the disk 
drives before using the EXPL command. EXPL searches for an explain command 
as follows. 


expl mail 

/ex pl/mail 

/cmds/mail.Silp 

/expi/mall/expl 

/expl/index 


look here first 
then here 
then here 
look here last 
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EXPL 


In many instances, the user may only wish to be reminded of die syntax of a 
command. All QNX commands explain their own syntax when the command is 
followed by a single question mark. 

expl ? 

You may use lines containing a formfeed (Ctrl-L) to cause EXPL to pause for 

input. Upon receiving a carriage return the screen will be cleared and EXPL will 
continue. 

The expl command will strip all escape sequences which apply to the system 
console when output is redirected. The +qnx option can be used to force the 
sequences to be printed when the user is logged in to QNX via a modem on a PC 
using QTALK. 

It is possible to construct a file which implements a single level menu using 
EXPL. The file will consist of a menu followed by two formfeeds on a line by 
themselves. Following this will be one section terminated by two formfeeds for 
each menu section. Each section may contain several single formfeeds to cause 
EXPL to pause at appropriate places. A formfeed may be entered using ED by 
typing a Ctrl-L. 

FF - one formfeed 

text 

. - this section contains a menu 

FF FF - two formfeeds 

text 

. - menu item or 9 a 9 or 9 A 9 or FI 

FF FF - two formfeeds 

text 

. - menu item 9 2 9 or 9 b 9 or 9 B 9 or F2 

Please refer to the file /expl/inform for an example of a menu driven explain file. 


[EXPL] 
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fbackup [drive] INit max-numr-files [c=360K 1720K11.2M 11.4M] 

["v=voljiame"] 

[f=formatjcommand] [-format] 


fbackup [drive] Files [archjlir] [+summary] [+|-verbose] [options]* 
fbackup [drive] NAme 

fbackup [drive] SAve save_spec* [+all] [-clr] [1 -levels] [options]* 

fbackup [drive] REstore [disk_dir[,arch_dir]] [-create] [options]* 

fbackup [drive] YErify [disk_dir[,arch_dir ]] [options]* 

save_spec: disk_dir[,arch_dir] x-indexJile filename[,arch_dir] 

options: +pause -verbose -multi_sector +hst-only + write 

pf =[\filej)attern pd=[]dirjpattern pp =[]pathjpattern 
-fbefore d -dd-mm-yy t-hh:mm:ss (Use digits) 

+Force (allow use of non-floppy disks) 
g-group m-member 
e-errorJile 

”v=volumejiame" (Use quotes if name contains spaces) 

Description: 

The FBACKUP command is used to archive large files to one or more floppy 
disks. This command was created to solve the need for saving files which are 
larger than a floppy disk (such as files used in most data base applications. Each 
time a file is saved it is appended to the end of the archive which may span many 
diskettes. Earlier versions of the same file will NOT be overwritten. You may 
restore any version of a file on the archive. 

The FBACKUP command should not be used as a general substitute for the 
BACKUP command. Performing an archive of all files which changed each day 
will rapidly consume large quantities of disks due to duplication. 


[FBACKUP] 
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When saving a smaller number of files, FBACKUP is dramatically faster than 
BACKUP and does not suffer the problems of disk overflow. FBACKUP will 
prompt for new disks as required. If FBACKUP is being used with the 4-Force 
option that allows archiving to hard disks, the CRON utility should also be 
investigated, as CRON can cause this backup to automatically occur overnight. 

There are many options for this command and to properly use it, the Floppy and 
Tape Backup technical note at the back of this manual should be read. 

See Also: 

BACKUP CRON TBACKUP 
Floppy and Tape Backup Technical Note 
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FBFORMAT - Format floppy diskettes 

Syntax: 


fdformat drive [options]* 

Options: 

f '-firstjrack 

1 -heads 

1 -lastjrack 

m-sectors! track 

$-stagger 


t -tracks 

-stagger 

+patch 


-pause 

+other 

b=sector_base 
+hard 
+abort 

+360k 
+720k 

+1.2meg 
+1.4meg 

Examples: 

fdformat 2 - Format diskette in drive 2 

using defaults. 

fdformat 1 +1.2 - Format 1.2M diskette in drive 1 


- First track to format (default: 0). 

- Number of heads 

(default 2). 

- Last track to format 

(default: last track on drive). 

- Number of sectors per track 
(8, 9,10,...). 

- Stagger factor (sector interleave) 
default stagger is 3 for n=8 

4 for n=9,10 
2for n=15. 

- Number of tracks on diskette 
(40 or 80 for diskettes). 

- Suppress the staggering of sectors. 

- Write the diskette size information 
indicated by h=, n= 9 1= onto block 
one of the diskette. 

- Suppress the prompt to load the 
disk. 

- Not a QNX style disk ("other”) - do not put the 
QNX size information in block 1. 

- block number to start sectors at. Usually 1. 

- Allow formatting of an AT hard disk. 

- Abort on error. 

- Assume 360K floppy (h=2, n=9, t=40). 

- Assume 720K floppy (h=2, n=9, t=80). 

- Assume 1.2M floppy (h=2, n=15, t=80). 

- Assume 1.4M floppy (h=2, n=18, t=80). 


[FDFORMAT] 
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•FDFORMAT 


overriding defaults. 

fdformat [3]2 t=80 - Format 80 track diskette 

in drive 2 of node 3. 

fdformat 3 +h s=6 

- Format partition mounted as disk 3 
with a stagger factor of 6. 

fdformat 3 -fti s=6 f=l 1=152 

- Format first 153 tracks of 
hard disk 3 with a stagger 
factor of 6. Skip track 0. 



FDFORMAT allows diskettes to be physically formatted using the floppy disk 
controller hardware. New diskettes must be formatted before they can be read or 
written to by the disk hardware. In addition, a newly formatted diskette will 
typically have to be initialized using the DINIT command before it can be used by 
the QNX file system, unless DCOPY is being used to make copies of already 
initialized diskettes. 

CADAD 11A A HP AlcArczlri'cs thk&k AvAttol if 
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MOUNTed. You can override the defaults by specifying parameters to the 
command. Floppy disk drives have three physical parameters of interest. The 
number of sides (single or double), the number of sectors (8, 9, 10 or 15) and the 
number of tracks (40 or 80). 

The t -tracks option allows you to format a diskette with 40 tracks or 80 tracks. 
Note that 80 track floppy drives are mechanically different than 40 track drives. 
You can read a floppy diskette formatted with 40 tracks on an 80 track drive by 
double stepping, but you can NOT format or read an 80 track diskette on a 40 track 
drive. 

The n-sectors!track option allows you to format a diskette to hold more or less 
information than the default size. For example a 360K floppy diskette (40 tracks, 2 
heads, 9 sectors/track) can be formatted to hold 320K or 400K by specifying n=8 
or 11=10 sectors/track. This option is independent of whether the drive is single 
sided or has 40 or 80 tracks. You should use high quality floppy disks if you use 10 
sectors/track. A value of n=15 may only be used on special high performance 
drives which may contain 1.2 Meg (2 heads * 80 tracks * 15 sectors/track). 
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FDFOEMAT 


The following table may clarify things. 

Sectors/Track 


Sides 

tracks 

8 

9 

10 

15 

1 

40 

160K 

180K 

200K 

+300K 

2 

40 

320K 

*360K 

400K 

+600K 

1 

80 

320K 

360K 

400K 

+600K 

2 

80 

640K 

720K 

800K 

+1200K 


* - Default If no parameters are specified 
+ - Requires high performance AT disk drive and 
special high capacity floppy diskettes. 

This formatting information is encoded on the diskette and is queried each time a 
file is opened. This allows QNX to read differently formatted diskettes in a single 
drive without having to remount the disk. This encoded information overrides 
those that are specified by the MOUNT command. Diskettes formatted with 
VERY old versions of FDFORMAT (QNX 1.1), or perhaps other operating 
systems will not contain this encoded information. In this case the defaults 
specified by the MOUNT command will be used. You may use the +patch option 
to place the mount information on a diskette which for one reason or another does 
not contain it. The disk will NOT be re-formatted. 

The -stagger option disables the staggering of sectors formatted on the diskette. 

By staggering sectors by 3, a program will have two sector times (about 12 msec) 
to process one sector of data and still be able to read the next sequential sector on 
the same revolution of the disk. Although this slows down program load time from 
the disk, it can significantly increase program throughput! 

FDFORMAT may be used to format a floppy disk on another node. The disk may 
be indicated explicitly via a [node] prefix or implicitly by specifying a remdisk 
which you have mounted. 

Hard disks may be formatted if the +hard option is specified and the hard disk 
driver supports formatting. 

See Also: 

DCOPY 

DINIT 

MOUNT 


[FDFORMAT] 
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FDBSK _ 

FDISK - Create QNX disk partition 

Syntax: 

fdisk drive 

Options: 

drive - Disk drive to partition. 



FDISK allows you to partition a hard disk. The partition information matches that 
used by DOS. It is kept on the first physical block on the disk. 

IMPORTANT: FDISK must only be used when the file system is idle. No 
other users or programs can have open files when this utility is used. 

To create a QNX partition for the first time you must first mount a hard disk 
driver. For example: 

mount disk 3 /drivers/disk.xt 

This is explained in a technical note in your QNX manual. You do not need to 
specify an offset or size. You should now execute the FDISK command from the 
floppy. 

fdisk 3 

and partition your disk. QNX does NOT automatically mount any partition. Once 
you have created the partition, you should remount the disk using this partition. For 
example: 

mount disk 3 /drivers/disk.xt pa=qnx 
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Specifying the pa= option will cause the MOUNT command to read the partition 
block, locate the first QNX partition, then mount the drive with the correct offset 
and size. You will probably wish to place this mount command in your sys.init so 
that it is executed each time you boot. If you are running the QNX-DOS file 
system task, you may also wish to mount a DOS partition as another drive. For 
example: 

mount disk 4 d=3 pa=do§ 

Note that you should NOT remount the driver. The d= option indicates that the 
existing driver which has already be mounted for disk 3 should be used. 

It is important to realize that the FDISK command only displays and updates the 
partition information on the disk. It does NOT directly affect your access to the 
drive. You must still issue the MOUNT command separately. 

FDISK is a full-screen, interactive program which is fairly self explanatory. When 
fdisk is invoked, it will display a screen similar to that shown below: 


Ignore 

Next 

Prev Change Delete Mount 

Boot Unboot 

Save Quit 


OS 


start 

End 

Number Boot 


name 

type 

Cylinder 

Cylinder 

Cylinders 

Blocks 

—> 1 . 

dos 

( 1) 

0 

139 

140 

19039 

2. 

qnx 

( 7) 

140 

279 

140 

19040 * 

3. 

qny 

( 8} 

280 

419 

140 

19040 

4. 

qnz 

( 9) 

420 

639 

220 

29920 

Use up/down 

arrows 

: to select 

partition. 



Type the letter c to change/add a partition. 

Type the letter s to save your changes. 

Type the letter q to quit. 

QNX is os type 7, 8 or 9 DOS is os type 1 or 4 Unused is os type 0 

First cylinder is 0 Last cylinder is 639 
Disk is 44,564 , 480 bytes H-8 T=640 N=17 
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The Possible commands are displayed along the top line. They can be selected by 
typing the first letter of the command, or by moving the cursor to the appropriate 
command (with the arrow keys), and typing Enter. 

The commands are described below: 

BOOT 

Make the selected partition the boot partition. 

CHANGE 

Change the selected partition. You must input an OS type, a start cylinder and an 
end cylinder. 

DELETE 

Delete the selected partition. 

IGNORE 

This menu item does nothing. It is a safeguard against accidental carriage returns 
which select the current menu item. 

MOUNT 

Display the parameters which you would give to the MOUNT utility for this 
partition. 

NEXT 

Select the next partition. The down arrow key may also be used. 

PREV 

Select the previous partition. The up arrow key may also be used. 

QUIT 

Leave the FDISK command. Remember to Save first, if you have changed 
anything. 

SAVE 

Save any changes made to the partition back to the disk. Unless this command is 
executed, your changes will be ignored. This allows you to quit without saving if 
you mess things up. 

UNBOOT 

Clear the boot indicator from the selected partition. 

NOTE: If you wish your disk to contain both QNX and DOS partitions? be 
sure to create the DOS partition FIRST (using DOS) 
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See Also: 

MOUNT 


Utilities 


[FDISK] 



FILES - List Files 


Syntax: 


files [ directory ] [options]* 

Options: 


-fbusy - Display only files which are busy. 

+directory - Display directories instead of files. 

+current - Only display files at the current level. 

+modified - Display files which have been modified 

since the last backup. 

“Sort - Don’t sort filenames. 

-used - List files which have been FRELed or ZAPped. 

-verbose - List only the name of each file. 

+verbose - List detailed information about each file. 

+totals_only - Only print totals of blocks and files. 

t=hh:mm:ss - Only print files which have a date later than 
this time on the given date. 

d=dd-mon-yy - Only print files which have a date later than 
this date. 

+Before - Applies to the t= and d= options. 
a=[& I A ]attr_list 

- List files whose attributes correspond to attrjist 
where attrjist is one of maewrc. 
p -pattern - Only display files whose name matches 

this pattern. 

Examples: 


flies 

files /cmds -s 
files +v 

files 3:/a=&rw 

files 3:1 a= A w 
files +d -v >lndex 

files 3:1 p= : Lc +v 

files 3:1 d=10-06-90 


List files at current directory. 

Unsorted list of files in /cmds. 

List ALL information on files 
at current directory. 

List all files which have the READ and 
WRITE attributes set. 

List all files which are not WRITEable 
List directories, don’t sort, then 
place output in the file index. 

List files on drive 3 which end in .c. 

List files with dates later than 10-June 1990. 
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Description: 

The FILES command allows the user to list the files at or below any point in the 
file structure. If no directory is specified, then the current directory is listed. The 
FILES command will walk the entire tree structure recursively, displaying all files 
at the specified (or current) directory followed by all files at lower levels. The +c 
option prevents the recursive walk of the file "tree", causing only those files at the 
current level to be displayed. 

Normally, file names will be sorted before being displayed. This feature can be 
turned off by specifying the -s option, in which case file names and directories will 

be displayed in the order they are found. When sorting, files at the current 
directory will be displayed first, followed by any files at lower levels in the 
directory. 

Directories are just special files in the QNX file system. The Files command will 
normally not print directories. If the user wishes to examine the directories which 
exist at this and lower levels, he can use the +d option. The ~s and +c options apply 
to directories as well as to files. 

If desired, only files whose filename matches a pattern may be displayed. The 
pattern is specified using the p= option. A pattern can be any valid filename, and 
may include the following wildcards: 

* matches any run of characters 

? matches any one character 

[ ] will match any of the characters enclosed in the square brackets 

An example pattern which will match any file which ends in ".c" or M .h" is 
"p=* [ch]". 

The +v option can be used to display the information about each file which is kept 
in the directory. One line of information will be displayed for each file, with the 
filename displayed last. The following information will be presented: 

Blk - Number of disk blocks in the file (512 bytes per block) 

X - Number of Extents in the file (indicates degree of disk 

fragmentation). A contiguous file will consist of one extent. 

Loc - Starting location of the file (hex block number) 

Grp - Group number of file owner. (1... 255) 

Mem - Member number of file owner. (1... 255) 

Attr - Attributes of the file. These are the access methods permitted for the 
owner of the file (or the super-user and privileged commands) 
Perm - Permissions. These are the access methods available to users other 
than the owner of the file. G-perms apply to other members of the 
same group. O-perms apply to to all other users. 
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Date - Date that the file was created or last changed. 

Time - Time that the file was created or last changed. 

Name - File name (relative to the specified directory). As deeper levels of 

the file structure are displayed, the complete hierarchical pathname is 
displayed. 

Attributes and Permissions for FILES may be: 

r MEAD permission. The file can be read. 

w WRITE permission. This file can be written to. User programs can 

therefore change the file contents and even delete the file (since null files 
are removed) 

a APPEND permission. The file can be written to, but only new information 
can be added to the end of the file. The file cannot be deleted. 

e EXECUTE permission. This file can be executed. If the file contains 
executable code, it can be executed directly. If instead it contains text, then 
the file will be treated as a command file, and the text lines will be given to 
the shell for interpretation. 

m MODIFY permission. This allows the permissions and attributes of the 
file to be changed (using CHATTR) 

Attributes and Permissions for DIRECTORIES may be: 

r READ permission. The directory can be read (listed). 

c CREATE permission. New files may be created under this directory. 

b BLOCK access. Prevent any files or directories below this directory from 
being accessed. 

m MODIFY permission. This allows the permissions and attributes of the 
directory to be changed (using CHATTR). 

d DIRECTORY. The file is a directory. 

If a file is BUSY, it will be flagged in the attribute column with a ’B’ character. 

The FILES command is a very useful tool for creating command files. A typical 
use of this function could be in the generation of a command file which is to delete 
all of the files at and below the current directory level. The user could start by 

typing: 

files “V >command 

which would create the file "command" containing a list of all the files at and 
below the current directory level. He could then edit this file and substitute the 
beginning of every line with "frel ", and save the file away: 

led command "*s/ A /frel/" w q 
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He could then execute the command file by typing: 

si command 

This example might be tetter accomplished using either the wild card syntax 'of the 
shell or the WS command. 

frel * 

or 

ws "frel 1=12 

A tetter use for such a file is on the creation of an index file for commands like 
LIST and LINK which support the x=index option. These commands expect to be 
provided with an index file of the form created by the FILES command. 

See Also: 

CHATTR 

DM 

LED 

■ LS 
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Syntax: 

fopen [node j [+uscriaj 



node - The node whose files you wish to query (default is your node), 

+eserid - Display a userid instead of the program which has a file open. 

Return Value: 

The return status is the number of files open 
or -1 on a critical error. 


FOPEN will print out the names of any tasks which have a file open. It not only 
indicates the program which opened the file, but also the open mode and the 
current location within the file. The location can be used to judge a programs 
progress in processing a file by invoking FOPEN several times. The location is 
shown as two numbers as follows: 

current Mock / last Mock 

This command can be used in a shell script r,o check if any files are open before 

shutting the system down. 

fopen 

if lie #? 0000 type "You have #? files opera Do not shut down the system," 

FOPEN only lists the files open on one node at a time. It defaults to your current 
node. You can specify a node using the node option. 

fopen 4 

See Also: 

DOPEN 



[FOPEN] 


Utilities 





FREE 


FREL - Release File 

Syntax: 

fre! file [file]* 

Examples: 

frel junk 

frel staff oldjunk test© 
frel [2] 1:/config/sy s.init 

Description: 

FREL will remove a file from the disk. The space esed by that file is reclaimed for 
use by other files, and the directory entry is removed. One or more files can be 
specified on the command line. 

If the file exists at the 'root of a disk, or if the same directory exists on multiple 
drives, then the filename should be preceded by the correct drive prefix to remove 
ambiguity. For example, use: 

frel 3:/test 

to remove the file "test" from the top level of the disk in drive 3. 

See Also: 

DREL 

RM 

RMDIR 
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FSTAT - Display file status 

Syntax: 

fstat file* [+xtnts] 

Options: 

file - A QNX filename. 

•f xtnts - Display the disk extents which 
are allocated to this file. 

Description: 

In its simplest form, FSTAT can be used to display die date of one or more QNX 
files. 

fstat /user/luc/testx 

fstat *.c 

If the +x option is used, then FSTAT will also give a complete list of all the disk 
blocks which are allocated to this file. This option is a useful debugging tool. 

See Also: 

DIR 

FILES 

LS 
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GREP - Search a file for a pattern 


Description: 

Please refer to the documentation on the LOCATE command. 

See Also: 

LOCATE 
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KBD - Redefine keyboard layout 

Syntax: 


kbd khdjype [f-userjile] 

kbd list [i=user_fiie] 

Options: 

kbdjype - Keyboard type to use 
list - List all keyboard types 

f-userjile - alternate file to use (default: Iconfigl kbd Abase) 

Examples: 

kbd 102.GE 

kbd 84.FR f=/eonf!«?/kbd.db.ours 

kbd list 

kbd list f=/config/kbd.db.ours 

Description: 

The KBD command remaps the character codes that are produced by your 
keyboard, using a binary data file {Iconfigl kbd Abase). You will only need to run 
this command if you are using a non-US keyboard. Users who require this 
command will likely execute it in their sys.init files. 

To find out what keyboard remappings are available, use the list option. The 
naming convention for a keyboard remapping is number Jceys .country _code 
where number Jceys is the number of physical keys on your keyboard, and 
country_code is typically a two letter abbreviation for a particular country. 

First, you need to figure out which keyboard you have. Specifically, you need to 
determine number Jceys. The simplest method is to count the number of key caps 
on your keyboard. Following is a brief description of each keyboard, and a picture 
of the default character mapping for it. 
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Below is the IBM PC/XT 83 key keyboard. It has ten function keys along the left 
side, and an integrated numeric/arrow keypad on the right side. 
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Below is the original IBM PC AT 84 key keyboard. It has ten function keys along 
the left side, and an integrated numeric/arrow keypad on the right side. 
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Below is the "enhanced” 101 key keyboard. It has twelve function keys along the 
top, and separate numeric and arrow keypads on the right side. It was first avail¬ 
able on the IBM PC AT, and later used on the IBM PS/2. This keyboard is only 
available with the US keyboard layout. 
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Below is the "enhanced" 102 key keyboard. It has twelve function keys along the 
top, and separate numeric and arrow keypads on the right side. It was first avail¬ 
able on the IBM PC AT, and later used on the IBM PS/2. This keyboard is only 
available with non-US keyboard layouts. 
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Once you have determined which physical keyboard you have, you need to 
determine which character remapping to use with it. Following is a current 
alphabetical list of the abbreviations for country_code, and their meanings. 


BE 

Belgian 

CF 

Canadian French 

DA 

Danish 

DU 

Dutch 

FR 

French 

GE 

German 

IT 

Italian 

LA 

Latin American 

NO 

Norwegian 

PO 

Portugese 

SE 

Swedish 

SI 

Swiss 

SP 

Spanish 

UK 

United Kingdom 

US 

United States 


If you do not specify an alternate file using the f= option, the file 
/config/kbd.dbase will be used. You may create an alternate file by copying the 
original /config/kbdAbase file, and possibly modifying the copy using the 
KBD_EDIT command, which is available from the update service. The f= option 
allows a user to avoid having their modified keyboard layouts overwritten by an 
updated /config/kbd.dbase file from QNX Software Systems Ltd. The keyboard 
remappings in /config/kbd.dbase should be accurate, and thus this option should 
rarely be used. 
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KILL - Kill a task 

Syntax: 

kill task-id 


® This is a local shell command 9 



The indicated tasks will be killed. You may obtain the tasks identity with the TSK 
command. KILL is supported by the shell to allow you to kill a task even when 
there are no free task descriptors in the system to create a new task. The escape 
sequence #& refers to the last background task you created. 

wii m 

If the first argument starts with a plus sign (+) it is taken as a system exception to 

set on the remaining taskid’s specified. For example 

kill +0001 050c -set exception hangup on task 050c 

Refer the to chapter on MULTI-TASKING in the QNX manual for more informa¬ 
tion on exceptions. 

You may wish to refer to the SLAY command to remove a task by if s name 
rather than if s task id. 


See Also: 

BREAK " 
SLAY 
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KILL VCS - Kill all virtual circuits to a node 

Syntax: 

kill vcs nodejd 

Options: 

nodejd - Node number of crashed node. 

Examples: 

kill_vcs 3 - Kill virtual circuits to node 3 

Description: 

The KILL__VCS command will kill all virtual circuits between your node and a 
node which has crashed. This allows manual recovery without using the poller. 
Please refer to the QNX manual on setting up your network. 

If a poller is running somewhere on the network, then this command should not be 
needed. 

See Also: 

ALIVE 

POLL 

TSK 
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LED - Line Editor 


Syntax: 

led i file [commands]} 

Examples: 

led 

lei junk 

led testx *s/b£ll/joe/ w q 

Description: 

The editor is a line oriented text editor which supports a number of powerful 
pattern matching facilities. Only text files can be edited, which means any files 
containing regular ASCII characters on lines which are terminated with a newline 
character (hex IE). Null characters (hex 00) are not allowed within the file. 

Lines are numbered sequentially starting from 1. Line numbers change 
dynamically as new lines are created and lines which are not needed are deleted. 
Lines can be referred to by specifying the line number explicitly, or relative to the 
current line (which is referred, to by the character "."). A line can also be referred to 
by specifying a partem of characters which is found on that line. Some commands 
support ranges of lines, which may begin and end with line numbers, relative line 
numbers, or lines containing patterns. 

Files are edited by first reading the entire file into a memory buffer. This provides 
for a very fast editor, and minimizes the dangers of having files open while editing. 
Unfortunately, very large files cannot be handled by this editor. It is recommended 
that large files be divided into several smaller files before editing. 

Files can be inserted anywhere into the editing buffer with the "r" command, and 
portions of the buffer can be written to any file (default being the current working' 
file). 
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Features supported by the editor are: 

- insertion before a line 

- append after a line 

- delete line(s) 

- write a group of lines to a file 

- append a file after the current line 

- character substitution on a range of lines 

- global command execution on a group of lines 

- join two lines 

- print a group of lines 

- change current line 

- location of lines containing patterns 

- moving a range of lines to another position 

- copying a range of lines to another position 

Editor Command Syntax : 

The format of an editor command is typically of the form: 

linerange command parameters 

where: 

command is the command character (described below) 
parameters are arguments to the command 

linerange is the range of lines which are to have 
the command applied to them. 


linerange can be: 
line 

or linejine 

or * 

line can be: 

lineno 


Ipatter nl 

line+nn 

line-nn 
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The characterrepresents the current line. The character "$" represents the last 
line. The character represents ALL lines which is the same as "1,$". The 
character represents hie lines from the current line to the current line plus page 

size (ie. one screen). 

Patterns represent a line which is found to contain that pattern. Patterns enclosed in 
slashes (/) mean the next line AFTER the current line which contains the pattern. 
Patterns enclosed in question marks mean the closest line BEFORE the current line 
which contains the pattern, scanning backwards. In both cases, scanning wraps 
around the beginning and end of the file and will terminate when the current line is 
again reached. 

Example line numbers and lineranges are: 


3 

- line 3 

1,10 

- lines 1 to 10 

6 

- the current line 

.+25 

.-10,.+5 ' 

- 25 lines past the current line. 

- all lines from 10 lines before the current 

line to 5 lines past the current line 

- the next line which contains the string "joe 1 

- all lines from line 1 to 4 lines past the next 

/joe/ 

1,/loop :/+4 

line containing the string "loop:" 

1,$ 

- all lines 

* 

- all lines 


Editor Patterns : 

The text editor allows pattern arguments to be used when locating line numbers, 
and when substituting strings. 

Several metacharacters are used when specifying a pattern, these are: 

A - represents the null character at the beginning of a line 

$ - represents the null character at the end of a line 

. - matches any character 

[ccc] - where V can be any characters, will match any one of the enclosed 
characters, (eg. [abc] will match any of "a", "b", or "c" 

[c-e] - where V is any character, will match any of the characters in the 

range of ASCII characters, (eg. [a-z] will match any letter) 

[ A ccc] - where "c" is any character, will match all characters EXCEPT those 
in the square brackets 

@(nn) - which represents the null character before character position nn. 
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Any of the above pattern characters may be followed by a star (*), which means 
zero or more occurrences of that pattern character, (eg. "a*" will match a null 
character, a, aa, aaa, etc.... ".*" is useful in matching a run of any characters) 

Preceding any character (including the metacharacters) with a backslash (\) will 
indicate that that character is to be taken literally, (eg. "\*" will match the character 
and 'W will match the character 'V). 

All other characters in a pattern are treated literally (ie. they will match only that 
character. 


Examples: 

will match "abc" anywhere in a line 
will match "abc" at the beginning of a line 
will match "abc" at the end of a line 
will match any character followed by "abc" 
will match any run of characters followed 
by "abc" ' 

will ixi&icn every tiling on a line 
will match the largest run of characters 
consisting only of numbers (which may 
be the null string) 
will match a number 
will match the largest run of characters 
which does not contain the digits 1, 2 or 3 

In string substitutions, two patterns are specified separated by delimeters, (eg. 
s/fred/bill/ or s,ed/,edit/,). The special metacharacter ampersand (&) is used to 
represent the portion of the line which was matched by the first pattern. This 
allows some very powerful editing operations. 

For example: 

s/[0-9][0»9]*/<&>/ - will turn the line "123 men on 3 horses" 

into the line "<123> men on <3> horses" 

s, A .*$,copy & dir/& 5 - will turn the line "junk.c" into the line 
’’copy junk.c dir/junk.c" 

When these pattern substitutions are combined with the global command (g), some 

very powerful editing operations can be performed. 


/abc/ 

/ A abc/ 

/abc$/ 

/.abc/ 

/.*abc/ 

/A *<£/ 

/[0-9]*/ 


/[0-9I0-9]*/ - 

/[ A 123]/ . 
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[line] a - Append new input after the line. 

End with a line containing 
a single ".*’ 

[range] ' c - Change these lines to new input. 

End with a line containing 
a single 

[range] d - Delete these lines 

efile - Edit new file...delete all lines, 

read in new file, 
and change current file name, 
f [file] - Change current file. If no file, 
then display current file name. 

[range] g!pattern! commands 

- Globally execute these ed commands 
on this group of lines. 

[line] i - Insert new input before the line 

End with a line containing 
a single 

[line] j - Join this line with the next line. 

[range] Mine - Make a copy of these lines 

behind the indicated line. 

[range] m line - Move these lines behind 

the indicated line. 

ocl char - Defines the command-line prompt 

character to be this char, 
oclchar - Defines the input prompt to be 
this char. 

oc3char - Defines the character to print when 
a null-line is entered. 

od - Dual-case is recognized in patterns, 

odr - Dual-case not recognized. 

Upper and lower case are the same, 
of - Display special symbols in expanded 

formNhh where "hh" is the hex value 
of that character. 

ofr - Turn off expansion of special symbols, 

op number - Define page size (for 
mnumber - Auto-save into file ’’autosave” after 
this many lines has been entered 
in input mode. 

ov - Display error messages upon error, 

ovr - Turn off error messages. Only display 

error number. 

[range] p - Print these lines. 

q - Quit if file not altered. 
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qq - Quit anyway. 

[line] r file - Read the file and put in buffer AFTER 

this line. 

[range] s/pattern/newl 

- Substitute aU occurrences of this 

pattern for the new pattern within 
this line range. 

[range] snumber/pattern/new/ 

- Substitute the Nth occurrence of the 
pattern, 

[range] \/pattern/commands 

- Execute the ed commands on all lines 
EXCEPT those with this pattern, 

[range] w [file] - Write these lines to the file 

& - Print a page (size defined by 

"op" command). 

[line] - - Display this line number (eg. ".="). 

CR - Display next line. 
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LINK - Link object files 

Syntax: 

link [o=new_object_file] objfile* [options]* 

Options: 


+i - Intel addressing mode (default). 

+m - Motorola addressing mode. 

+v - Verbose. 

m-mapfile - Create a map and put in mapfile. 

o-obj jile - Create a new object file, 

u =sym - Use the symbols found in sym 

but do not include the code or data. 
sl-hhhh - Segment 1 starts at hhhh (hex). 

§ 2 -hhhh - Segment 2 starts at hhhh (hex). 

s3=hhhh - Segment 3 starts at hhhh (hex). 

s4-hhhh - Segment 4 starts at hhhh (hex). 

sl=$n - Segment 1 starts AFTER segment n. 

s2=$n - Segment 2 starts AFTER segment n. 

s3=$n - Segment 3 starts AFTER segment n. 

s4 =$n - Segment 4 starts AFTER segment n. 

s-stack - Increment to minimum stack size. 


c -loadfile - Put output file into loadfile 
(default is "core”). 

x-index - Link the object files in index. 

\-library - Search directory library for 

any unresolved functions and variables. 

A file named '7/&rary/directory" must be found 
which lists symbols defined in each object file, 
n -namelen - Maximum length of a name (default: 66). 
b -bufsize - Size of symbol buffer (default: 32000). 


Examples: 


link /Itb/eetryaO test.o 

link x=edfl!es ra=.map. !=/lib s=4000 

link o=ed.o x=ofi!es +v 


link u=rom.map rom.o m=map sl=ffc0 s2=1000 s3=$2 
link o=$nulI test.o +v 
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Description: 

The routine CC should be used instead of LINK for linking programs to run on 
QNX. CC will invoke LINK with the proper arguments to create a load file for the 
QNX environment. Any arguments to CC are passed on to LINK. The same is 
true for any extra arguments passed to the CC command. LINK may be called 
directly to link programs for environments other than QNX. 

The Linker will link together object files which are created by one of the compilers 
or the assembler. A load file is produced which is in a form to be executed directly 
(by typing its name on the command line). All external references are resolved, and 
warning messages are printed if any object module references a symbol which is 
not defined in any other module. 

The default values for the 4 segments which are allowed by the assembler are such 
that if no overriding values are specified, the command will execute properly. 
Overriding segment starts and offsets are typically only used when linking together 
object files which are not to be executed as a command. For example, a program 
which is to be placed in ROM would need to be linked outside of die default 
memory segments. 

The x= option accepts a file list in the form which would be created by the FILES 
command, allowing convenient linking of commands which consist of a large 
number of object files. Therefore the format of an index file is with one object 
filename per line. 

The 1 = option invokes a search for unresolved symbols under the specified 
directory. A file named "directory" is used to define the contents of this library of 
object files. The format of this file is one object file name on a line by itself, 
followed by any number of lines which begin with a TAB character followed by 
one symbol which is defined in that object module (see the file "/lib/directory" as 
an example). Any number of object files may be described in the library file. 

" Multiple 1 = options are allowed so that many libraries can be searched. All library 
references must be forward. Refer to the documentation on QNX compilers in 
your C binder for more information. 

Program execution begins with the first address in segment 1 which is typically the 
code segment. 

By default, all commands are given a IK stack by the operating system. The s= 
option in the linker allows additional stack space to be allocated. 

The linker will create a map file if the m= option is used. This map is useful when 
debugging programs. The address (hex) of all functions and variables is included in 
the map. Typically the map should be sorted with the SORT command if it is to be 
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used in debugging a program. 

sort mapfile s=l,3 +r (sort by name) 

or 

sort map file s=l,2 +r (sort by address) 

The linker can take a collection of object files and combine them into one large 
object file using the o= option. It must immediately follow the LINK command. 
The sl=» s2=, s3= and c= options are not used. 

link o=ed.o main.o command.© output.o input.o +v 

Note that this option may be used to determine the size of an object module. In 
this case the output is thrown away. 

ink ©=$ftull objfile.o +verbose 

There is no limit to the number of object files which can be linked together 
provided that the resulting command will fit within the address limitations of the 
processor (64K code + 64K data). If the code segment is exceeded, you will need 
to refer to the the technical notes in the C Compiler binder. 

LINK maintains its symbols in an allocated buffer. This buffer defaults to 32,000 
bytes, but may be changed with the b= option. If LINK complains that it has ran 
out of symbol space (for very LARGE programs), try again with a bigger buffer. If 
memory is tight on your machine, you may wish to decrease this value. Valid sizes 
are 2000 to 65,520. 

See Also: 

ASM CC 

SORT Technical Notes (C) 
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LIST - List files on the line printer 

Syntax: 

list [options]* [file]* 

Options: 



b-banner 

d-device 

i=file 

l-page_length 

n -name. 

Q-offset 
p-port 

s =vert_spacing 
w~line_width 
t =tab[ 9 tab]* 
n-indexjile 

+numberlines 

preset 

+gap 

+assembly 

+listing(assembly) 

4-emphasized 

-emphasized 

+double_print 

-double_print 

-pagination 

-header 

+banner 

+user 

Examples: 


- Name of banner on first page. 

- Name of $device to use for output 
(default: taken from prt.init). 

- Printer configuration file 
(default: /cmds/prt.init). 

- Define page len in inches (default 11). 

- Name to print in header 
(default: filename). 

- Offset from left hand margin. 

- Define semaphore port (default 16). 

- Vertical spacing (lines per inch). 

- Characters per line. 

- Define tab stops. 

- File containing list of files to 
print. 

- Print line numbers with listing. 

- Reset page number to 1 for new files. 

- Feed a gap for a new banner. 

- Set tabs for assembly source program. 

- Set tabs for assembly listing. 

- Turn on emphasized printing. 

- Turn off emphasized printing. 

- Turn on double printing. 

- Turn off double printing. 

- Turn off pagination (and headers). 

- Turn off header (date and page no.). 

- Print a banner page. 

- Print user numbers on each page. 


list test.c 

list s=8 w=80 o=10 report 
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list +a ,f n=ASM Files" x=assembly_index 

list +g 

list +b -p -h w=80 s=6 +e gooddocument 

files +¥ | list & 

Description: 

LIST provides a means of printing paginated output on a line printer. The date, 
time, filename, and page number are printed at the top of every page. More than 
one file can be specified on the command line. Index files may also be used which 
contain a list of files to print with the current option settings. More than one index 
file can be specified. The format of an index file is that of the output of the FILES 
command (with the -v option). 

Tabs are expanded into spaces by the LIST program. The default tab stops are at 
every 4th character position. This can be changed with the t= option. If more than 
one tab stop is given, then LIST will assume that tabs past the last specified tabstop 
will have the same spacing as the gap between the last two given tabstops. For 
example "t=4,7" will put tab stops at position 4,7 and then every 3 positions 
afterwards since the difference between the last tabstop (7) and the previous one 
(4) is 3 spaces. 

For printers which support different line spacings, the s= option allows the user to 
select the line spacing (eg "s=6" for 6 lines per inch, "s=8" for 8 lines per inch). 
Some printers also support different character widths. Character widths can be 
changed using the w= option. Examples are "w=80" for 80 characters per line and 
"w=132" for 132 characters per line (on an 8 1/2 inch page). 

Some printers (such as the MX-80) allow special print modes such as emphasized 
printing (use +e) or double printing (use +d). 

If listings are to be placed in binders, a margin is often desired on the left side of 
the page. The o= option will offset all output the specified number of spaces to the 
right to leave such a margin. 

When used with the banner option (+banner) the first page of a listing contains a 
"banner" which gives the current date and time as well as the name of the first file 
being listed. A different banner can be specified with the b= option. In this case the 
LIST program will always feed enough spaces after the last file has been printed to 
allow the user to remove his listing without needing to feed the paper himself. The 
resulting gap is used by the next LIST command for its banner. This mechanism 
works well provided that the user only uses the LIST program to generate output 
on his line printer. To initially position the paper at the correct position for printing 
banners, the user should position the paper to the top of a new page, then issue a 
"list +g" command which will feed the proper number of spaces. Subsequent LIST 
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commands will then be positioned properly. This procedure is especially useful for 
printers which don’t support formfeeds. 

The LIST program also provides a means of turning off the printing of the top-of- 
page header (-h), and/or the automatic spacing between pages (-p). This allows the 
user to print documents which don’t require these features, but still be able to 
specify line spacings, print modes, etc. 

The LIST command will automatically wait for other LISTs to finish before 
printing. This automatic spooling is especially useful in multi-user installations 
where many users wish to print files at the same time. So long as everyone uses 
LIST to print their files, the listings will not be mixed together. 

The characteristics of the line printer are found in the file 7cmds/prt.init". This file 
name may be over-ridden using the i= option. If no configuration file exists, then 
the LIST program assumes that it is talking to a printer which prints 80 characters 
per line at 6 lines per inch. An example format of the file 7cmds/prt.init n is shown 
below for the EPSON MX-80 printer. All numbers are decimal unless followed by 
the character ’IT or ’H’ in which case they are hexadecimal. These numbers often 
represent ASCII characters. Note that the comments in the following example 
should not be included in the file. 


$lpt 

name of printer (may be overridden using d=) 

12 

form-feed character (0 if not supported) 

132 

default width for listing (characters per line) 

8 

default spacing for listing (lines/inch) 

80 

default width for headers 

80 

default width for banners 

6 

default spacing for banner page 

80 

WIDTH #1 (characters per line, 8 1/2" page) 

20 18 

string to print to cause this line width 

132 

WIDTH #2 

20 IS 

string for width #2 

0 

END of widths 

6 

SPACING #1 (lines per inch) 

27 50 

string to print for spacing #1 

8 

SPACING #2 

27 48 

string for spacing #2 

0 

END of spacings 

27 69 

string to print for +e 

27 70 

string to print for -e 

27 71 

string to print for +d 

27 72 

string to print for -d 
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See Also: 

p ■ 

SPOOL 
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LOCATE - Locate patterns of characters in a file 

Syntax: 

locate " pattern " [file I x=file]* [options]* 

Options: 

c-context 
b-bytesJo _skip 

w~pattern 

x-file 
+dualcase 
+count 
“Verbose 

Examples: 

locate array teste 

locate INV main.c support.c x=index junk.c +d 
locate "([a-zJta-z]*)" *.c -v 

Description: 

LOCATE will find patterns of characters in a given file (or files). The name of the 
file, and line number will be displayed along with the entire line, for each line in 
the file which contains the pattern. Patterns are the same as those used in the LED 
command. 

Index files may be used to avoid typing long strings of file names on the command 
line. The format of these index files is the same as the output format of the "files 
-v" command. 

Consider a directory called /application which contains several C source programs, 
and perhaps several object files as well. To find all the C source files which 
contain a call to the function "sort", the user could use the following: 

files /application -v p=*.c >index 
locate sort( x=index 
OR 

locate sort( *.c 


- Number of lines to print for each match. 

- Number of bytes to skip before starting the locate. 

- After a match continue output while following 
lines match pattern. 

- Index file containing list of files to search. 

- Distinguish between upper and lower case. 

- Exit with number of finds. 

- Don’t display filename and line number. 
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This will produce one line of output for every occurrence of the pattern "sort(" in 
all these files. The LOCATE command will also supply the filename and line 
numbers where these patterns occur. The WS command is often used with locate 
for the same purpose. 

ws "locate sort( p=*.c 

Normally, upper and lower case letters are treated identically. The user can specify 
+d which will then distinguish between upper and lower case letters. 

The -v option turns off the display of filename and line number at the beginning of 
each output line. 

The w= option permits simple lookup databases to be implemented with simple 
text files created by the editor. For example, a file could be created with keywords 
followed by lines of descriptive text which are indented by one or more spaces. To 
print the text associated with a keyword "QNX”, one could issue the following 
command: 

locate A QNX "w= A " -v 

The LOCATE COMMAND can be used in SHELL scripts to count the number of 
occurrences of a string in a file. The +count option is useful for this. 

The c= option allows some context to be printed around each matching line. For 
example, specifying c=5 would print each line containing the pattern, along with 
the next 4 lines (5 lines of context ). The c= and w= options cannot be used at the 
same time. 

See Also: 

FILES 

LED 
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LOCKER - Implement record locking In QNX 

Syntax: 


locker [options]* & 

Options: 

s-cachejize - Number of IK blocks to allocate for the cache. Default Is 64, 
minimum is 32, maximum is 1000. 

p -port - Port to attach to. Used for timing purposes to age the cache, 

h-bujfers - Maximum data segment buffers to be used. 

f-files - Max number of simultaneous open files. 

+d ebug - Internal use only. 

+sync - Force 0_SYNC option on all OPEN()’s. (See the C compiler 

manual for details) 

Description: 

LOCKER implements a record locking facility in QNX. To make use of it, 
applications must have been written specifically to use LOCKER. LOCKER is 
usually started from the sys.init at boot time, and left running always. The 
b-buffers option us used to set the number of data segment buffers to be used by 
LOCKER (max approx 30). The larger this value the less room there is for locks, 
task entries etc. 

If you need to terminate LOCKER, use the SLAY command: 
slay locker 

Although no QNX Software Systems applications are using LOCKER (as of 
January, 1988), this may not always be true. However, a number of 3rd party 
applications (notably database products) are using locker. If you have any doubt as 
to whether or not you should run locker, check the documentation for the applica¬ 
tions you wish to run, or contact the vendor or QNX Software Systems’ technical 
support. 

LOCKER requires the presence of TIMER. Before starting LOCKER, you must 
invoke TIMER (it is used to age the cache). For example: 

timer & 
lockers=100 & 
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See Also: 

TIMER 

Record Locking in QNX in the C manual Technical Notes 
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LOGIN - Log-in to QNX 
Syntax; 


login [userid [password]] [+stack] 



userid - Name of user: (Max 16 characters). 

password - Unique password for that user. 

(Max 20 characters). 

+stack - Stack logins, freeze current user. 

Examples: 

login 

login bill secret 
login john +s 

Description: 

LOGIN allows a user to log-in to a QNX system. QNX will invoke LOGIN on the 
console automatically when the system boots. LOGIN will also be invoked if a 
user types Ctrl-Z on any idle terminal or console. 

If invoked with no arguments (such as with automatic invocation by QNX), 
LOGIN will prompt the user for his user-id and password. The user will be greeted 
with a message of the form: 

QNX version x.xx (Release x) 

Copyright © QNX Software Systems Ltd. 1982,1993 
Login: 

The user-id supplied by the new user is checked against all valid user-ids found in 
the file 7config/pass\ If a match is NOT found, then LOGIN will re-issue the 
message: 

Login: 
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If the user-id DOES match one of the entries in the password file, then LOGIN 
will prompt the user for a password: 

Password: 

This password must match the one found in ’/config/pass’. If it does not, then 
LOGIN will re-issue the login message. If the password was found to be correct, 
then LOGIN will create the user. The user’s number (group.member) is assigned 
from the password file, as is his home directory. An initial command is also 
executed automatically, if one exists in the password file. Finally, LOGIN will 
create a SHELL on the terminal for the user to use. 

Once a user has successfully logged-in, he may use LOGIN to log-in to another 
user. If +stack is not specified, then LOGOFF will be called automatically. If a 
valid user-id and correct password are given to LOGIN, then that user will be 
logged-in without prompting for these values. If both fields aren’t supplied (or are 
incorrect), then LOGIN will issue the login prompt and wait for a valid user-id. 

See Also: 

LOGOFF 

SH 
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LOGOFF - Terminate a QNX Session 

Syntax: 

logoff [-Z] 

Options: 

-z - Don’t print message regarding Ctrl-Z. 

Examples: 

logoff 

logoff -z 

Description: 

LOGOFF is called by a user to terminate Ms session with QNX, All resources 
which were used by the user will be reclaimed by the operating system and his 

accounting entry will be deleted. 

If the -z option is not specified, a message of the form: 

......... Type a Ctrl z to login ——— 

will be displayed to remind the next user of that terminal to type a Ctrl-Z to log in. 

See Also: 

LOGIN 

SH 

QNX Manual 


[LOGOFF] 


Utilities 








LPS - List Postscript Laser Printer Filter 

Syntax; 


lps [file]* [options]* 

options: +align +(crt) 4-duplex 4-Duplex 4-header 4-landscape 

4-Landscape +pchars 4-verbose +quad 4-Quad +octal +Octal 

SL=alignfactor[44Q] K-align_char c=columns[l] f-font[4] 
{-ignoredjpages k -copies l-maxlines n-pagesjo_print 
Q-offset O-offset p =cur_psize[ 12] r -rightmargin 
s=extra_spacing sx=x_scale sj=y_scale 


+align 

+(crt) 

+duplex 

+Duplex 

+header 

4-landscape 

4-Landscape 

4-pcfaars 

4-verbose 

4-quad 

4-Quad 

4-octal 

4*Octal 
a -alignfactor 


- Turn on auto-alignment feature. 

- For each letter entered, map that letter when enclosed by 
parentesis into the symbols (• c)->© , (• r)->® and (• t)->™ . 

- Print two pages on one physical page in landscape mode. The 
logical pages are scaled, rotated and translated to fit. 

- Same as 4 -d except the page offset is applied to the logical 
page printed on the right side of the physical page. 

- Display the filename as a header on each page printed. 

- Rotate the logical page to print sideways on the physical 
page. If more than one column is printed the page offset is 
only applied to the first column. 

- Same as 4-1 except the page offset is applied to each extra 
column printed when t-columns is specified. 

- Support the codes for the PC line drawing characters. These 
characters are defined in the file /config/pcfoetps. 

- Print a comma (,) for each logical page skipped and a period 
(.) for each logical page printed. Remember that several 
logical pages may be printed on one physical page. 

- Print four pages on one physical page in portraite mode. The 
logical pages are scaled and translated to fit. 

- Same as 4-q except the page offset is applied to the logical 
pages printed on die right side of the physical page. 

- Print eight pages on one physical page in landscape mode. The 
logical pages are scaled and translated to fit. 

- Same as 4-0 except the page offset is applied to each logical 
page. 

- Set the width of the alignment character in 100 * points. The 
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A=align_char 

t-columns 

f=font 

i=numpages 

k=copies 

l=maxlines 

n-numpages 

^-offset 

0 =ofjsei 
p -points 

r-rightmargin 

s=spacing 

s upscale 
sj=scale 

Examples: 


default is 440. 

- Two character hex value which represents the alignment 
char. The default is the backquote C)> hex 60. 

- Select the number of columns to place on a physical page. 
Each logical page starts a new column. 

- Select the font to start printing with. It defaults to Times 
Roman. 

- Ignore (skip) this number of logical pages. Note that several 
logical pages may print on one physical page (ie: +dual, 
c=columns ...). 

- Number of copies to print for each page. The default is 1. 

- Force a new logical page after receiving this number of lines. 
Useful when text is pre-formated without formfeed 
characters. 

- Only print this number of logical pages. Note that several 
logical pages may print on one physical page (ie: +dual, 
c=columns ...). 

- Specify a page offset (left margin) in points. Defaults to 36 
points (1/2 inch). 

- Same as o= except the offset is applied to all columns and not 
just the first column. 

- Select the pointsize to start printing with. This set the 
‘ pointsize for a logical (full size page). The +dual and 

+quad options scale it. It defaults to 12 point. 

- Specify a right margin in points. Used for justification only, 
lines are not broken. Defaults to 468 points (6 1/2 inches) 
from left page border. 

- Specify extra points (1/72 inch) of space between printed 
lines. 

- Floating point number to scale charcater width. Do not use 
with the +d or +q options. 

- Floating point number to scale character heigth. Do not use 
with the +d or +q options. 


lps text o=72 >$mdm 

lps text +d >$mdm 

lps text +q >$mdm 

lps text +1 c=4 f=0 p=8 

lps text +1 c=4 f=0 p=8 sx=,75 

Description: 
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The LPS utility takes a text file and converts it into a set of postscript commands 

which will display it on a laser printer supporting postscript. There are a number 
of command line options which provide considerable flexability in the formating of 
the output. The utilty also recognizes a large set of escape sequences which can be 
embeded within the text to further enhance your output. For example, there are 
sequences to changes fonts, pointsize, attributes and underline to mention only a 
few. These escape sequences allow word processors and the QNX list command 
which do not support postscript to be used with a postscript laser printer. To find 
which fonts are supported by LPS type. 

Ips ? 

Note: Your printer may support fewer or more than those fonts listed. 

The size tables for all these characters are kept in the file /config/PSwidths. 
Programmers may use these tables for their word processors. It is structured as 

struct font_entry { 

char font jnarae[32] 
unsigned font_widttis[256] 

} font_fiie[NUM__FONTS]; 

with each value containing the characters width at pointsize 1000. Keeping the 
width as scaled integers saves the application from having to use floating point 
which is much slower. LPS also uses the following two files. 

/config/Prolog.ps - Pre-peeded to each job. 

/config/LineChars.ps - A Sine drawing character set. 

If you are familure with Postscript, you may edit and modify these files. In 
particular you may wish to add to the line drawing character set. 

LPS takes as input a series of logical pages and from them produces one or more 
physical pages. A logical page is what you would consider to be a full page of 
text. The end of a page is usually marked by a formfeed character or the end of 
file. If your text does not separate it pages with formfeeds but instead expects the 
printer to start a new page every nn (say 66) lines then you can specify a 1=66 
parameter to LPS to cause it to paginate based on this number. If your pointsize is 
too large for a logical page to fit on the physical page LPS will itself break the 
page when you run off the bottom. This allows you to take a completely 
unformated piece of text and run it through LPS without any options knowing that 
it will be paginated properly reguardless of the pointsize used. If you text contains 
formfeeds and you select too large a pointsize LPS will paginate on page overflow 
then again when it sees the formfeed character resulting in a second page which 
contains only a few lines of text. In this case you should reduce your pointsize. 
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Unlike a daisy wheel or dot matrix printer which maps one logical page to one 
physical page, the LPS utility can map several logical pages to one physical page. 
It does this by scaling the text, and then translating it to different area’s of the page 
instead of starting a new page. For example the +quad option puts 4 logical pages 
onto 1 physical page by scaling the x and y size by 0.5 and treating the physical 
page as 4 small pages by translating the output. The mapping looks like this. 



This has two advantages, for drafts it saves paper and on a 7 page/minute laser 
printer you can often achieve 20 logical pages/minute throughput. Each logical 
page displayed will also look the same as that produced when you go for a full 
page master of each logical page. The +dual option rotates the page and placed 2 
logical pages on one physical page. Each logical page is the same size as used in 
our manuals. When producing a master for a printer it is best to produce pages at 
full size and have the printer reduce them when he makes the plates. In the case of 
pages of the size you are now reading this reduction has the side effect of 
increasing you laser printers resolution from 300 dots/inch to over 400 dots/inch. 
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For those with good eye sight there is also a -foetal mode which prints 8 logical 
pages per physical page. The output is still quite readable (heh, heh) and if your 
laser printer can keep up, you can print at an effective rate of 8 times your laser 
printer’s page output rate. 

You can also place mutiple logical pages on the physical page by using the 
^columns option which will divide the page into the indicated number of 
columns. Each logical page will start at the start of the next column. In this case 
you have to select a pointsize which fit the text in the columns. Scaling is NOT 
performed automatically as it is with the dual and qaud options. You can also 
specify landscape mode to rotate the page. The options of +1 and c=3 would 
produce a physical page of. 



Physical Page 


The + dual and f quad options start the logical pages which are printed on the right 
side of the physical page exactly at in the middle. The page offset is only applied 
to the left side. If you specify a capital letter (+D, +Q) then the offset will be 
applied to the right side as well. In the case of dual printing this provides for a 
margin if you wish to cut the page in half and place it in a binder. 



+dual option 


+Dual option 


When producing tables with a variable width font they seldom line up. Each 
character has a differrent width. You can force alignment by adding a backquote. 
The +align option can be used to automatically add them for you. However, it 
makes certain assuptions and guesses which may not be what you want. When 
enabled, for each line LPS reads it will add them after a run of two or more spaces 
not preceeded by by a., ? or! and around dashes (-) and o’s (o) which are often 
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used for points. 


aiaiaia - Without alignment char on any of 

these lineSo 

axaxaxa - Without alignment char on any of 
these lines. 

aiaiaia. - With alignment chars on each side 

of the dash (**) and the start of 
text on each these lines,, 

axaxaxa - With alignment chars on each side 
of the dash (-) and the start of 
text on each these lines. 

Please note that a space is a very narrow character while a capital A is very large. 
Alignment is based upon an average which assumes that all characters are about 
the width of a small a. This will be true on average but fails badly when presented 
with all capitals. The line. 

AAAAAAAAAAAA "point one 

will actually slide the text "point one" to the left resulting in an overprint as 
follows: 

AAAAAAAAA|yiilt one 

This can be corrected by simply increasing the number of spaces before the point. 

AAAAAAAAAAAA ‘point one 

which produces 

AAAAAAAAAAAA point one 


You can use simple shell files to interface utilities like LIST to your laser printer. 
For example, the following shell file is suitable for producing listing of C programs 
on your laser printer. To conserve paper it prints with the +dual option and uses 
the courier font. Note that you will have to create a list initialization file which 
uses the escape sequences supported by LPS. 

list #* >/tmp/#n#t.lst i=/config/psinit 
Ips /tmp/#n#tlst f=0 +d >$mdm 
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If this file was called LLIST you can use it in place of LIST. 

llist filel.c f!!e2.c... 


Your laser printer is going to be very popular and you will want to share it amoung 
many users. This is most easily acomplished using the SPOOLER and SPOOL 
command. If your printer is attached to $mdm you should run the spooler as 
follows. 

spooler "crdps >$mdm ,, t=/tmp/ & 

You may wish to place this command in your system initialization file. You can 
now submit files using the SUBMIT command. 

spool su file any Ips options 

In the example of the LLIST shell command above you would replace the second 
line with LPS to a SPOOL SUBMIT command. 

Escape Sequences 

In the following tables some of the escape sequence take one or more ascii digits as 
parameters. They will be represented as italic (T s. 

d - A single digit. 

dd - Up to 2 digits. 

did - Up to 3 digits. 

dddd - Up to 4 digits. 

If several digits are expected you can supply fewer as long as you terminate them 
with a non-digit. For example if dd was expected then input would be interpreted 
as 

Ixyz - Read a 1 followed by "xyz" 

12xyz - Read a 12 followed by "xyz" 

123xyz - Read a 12 followed by "3xyz" 

123xyz - Read a 12 followed by ?? 3xyz" 

You may also enter a leading plus or minus sign to indicate a relative rather than 
an absolute change. 

ESC p 12 - Set pointsize to 12 points. 

ESC p +3 - Add 3 to current pointsize. 
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ESC p -3 - Sob 3 from current pointsize. 

There are two classes of escape sequences, single character and muti-character. 

The multi-character sequences always start with an ESC code (hex lb, dec 27). 

You will note that LPS supports the escape sequences supported by the system 

console. A file which highlights, underlines ... text on the console will do the same 
on the laser printer. Inverse is mapped to italics and blink to larger characters. 

The console colour escape seouences are ignored 

Note that center, fully justify and right justify are easily remembered by there first 
letter with a control key. The text following these codes extendes to another code 
or a code which forces a repositioning of the text (typically a newline). 

Single Character Sequences 

Name Ctrl Hex Action 

TAB Ctrl i 09 Move to next tab stop. Tabs fixed every 4. 

MS Ctrl A le Move to start of next line. 

CM Ctrl m Od Move to begining of this line. 

LF_ Ctrl j 0a Move down a line (same column). . 

ETX Ctrl c §3 Center following text between margins. 

ACK Ctrl f 06 Fully justify following text between margins. 

DC2 Ctrl r 12 Right justify following text between margins. 

ETB Ctrl w 17 Force a current position (moveto command) to printer. 

EOT Ctrl d 04 Ignored and striped from the text. 

FF Ctrl 1 0c End of a logical page (formfeed). 

The following will create a line with three parts. One part left justified, one part 
centered and one right justified. Text in < >’s represent a single character. 

UtI!If?es<ETX>© QNX Software Systems<DC2>LPS<RS> 


Multi Character Sequences 


Sequence 

Action 

ESC ( 

Italics on. 

ESC) 

Italics off. 

ESC < 

Bold on. 

ESC > 

Bold off. 

ESC [ 

Underline on. 

ESC] 

Underline off. 

ESC { 

Increase pointsize 1/3. 

ESC} 

Decrease pointsize 1/3. 

ESC# 

Pattern mask on. 

ESC : 

Pattern mask off. 

ESC d 

Subscript (move down 1/4). 
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ESC f dd 
ESC p ddd 
ESC u 
ESC m ddd 
ESC 6 
ESC g ddd 
ESC z d 
ESC z 4 cmd „ 
ESC o ddd 
ESC a d 
ESC F d 
ESC M ddd 
ESCS 
ESC R 
ESC b dd dd 
ESC y ddd , dtfdf 


Set font. 

Set pointsize in points. 

Superscript (move up 1/4). 

Set right margin In points. 

Display the quote char. 

Set gray level. 0 (black) to 100 (white). 

Add zing to text. 0 to 3 supported. 

Use postscript command to show text. 

Set page offset in points. 

Set aiito-align ©e (d=t) or off (</=0). 

Expand mask (Esc # 9 :) to right margin if d=h 
Manual feed the next ddd sheets of paper. 

Save font, pointsize, attributes and zing. 
Restore from last save (ESC S). 

Draw a box. If gray level != 0 then it Is filled. 
Move by points by x (col) and y (row). This 
is usually done as a relative move. 


The following sequences impliment the console cursor movement escape 
sequences. To be useful you should use the courier fixed point point. Proportional 
fonts may not line up as expected. 


Sequence 
ESC A 
ESCB 
ESC C 
ESC D 
ESCB 
ESC Y cc 

For special situations you may pass postscript commands directly to the laser 
printer by enclosing them in the follow escape sequence. 

SYN SYN postscript commands SYN 


Action 

Cursor up. 

Cursor down. 

Cursor right 
Cursor left. 

Cursor home. 

Direct cursor addressing. 


In conclusion, the following escape sequence can be used to create the shaded 
blocks with which each of our utilities start with. You will have to supply a 2 digit 
number for you right margin (margin) and the text to be outlined (your text). 

Both need to be provided twice. The right margin is provided in character posi¬ 
tions NOT points. The last two lines of the escape sequence vary depending on 
wheather you wish an odd or even page. 
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ESC S ESC B 

ESC g 095 CR ETB ESC b margin +04 
ESC g 000 ESC b margin +04 

ESC A 

Odd page (right justify) 

ESC ff08 ESC p +20 ESC g 100 DC2 your text CR 
ETB ESC g 000 ESC z 1 DC2 your text ESC R 

Even Page 

ESC f08 ESC p +20 ESC g 100 your text CR 
ETB ESC g 000 ESC z 1 your text ESC R 


See Also: 

SPOOL 

SPOOLER 


Save state and position 
Draw shaded rectangle 
Draw box outline 

Position 


Put text in white 
Put text in outline 


Put text in white 
Put text in outline 
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LS - List directory 


Syntax: 

Is [directory] [options]* 

+modified -sort p=[ A ]pattern +unused -dir_off 4-dir_on 
+age_sort +Size_sort +reverse_sort +size +blocks -All 

c—columns -columns_off -*-file_list ^horizontal +'verbose 

+executable -executable +Modified_only +clear_screen 
w- column_width +tx_time b=baud_rate -modified 1 -linejength 

Examples: 

Is +v 

Is /cmcls 

Is /user/bill/dirl -s 
Is +M p=*.c +c 

Description: 

LS displays a sorted list of all the files and directories which reside at the current 
(or specified) directory level. Directory names are preceded by a plus sign (+) 
indicating that there is a substructure below it. 

There are an almost unbelievable number of options: 


- Highlight files that have been modified since last backup. 
These files are shown with enhanced video mode or with a 
leading star (*) if enhanced is not available. The other files 
are also shown. 

- Show only files that have not been modified since last 
backup. Setting this flag also supresses the display of 
directories. 

- Show only those files that have been modified since last 

backup. Setting this flag also supresses the display of 
directories. 

- Supress all sorting of the output. Files appear in the order in 

which they exist in the directory file. 

- List all file entries which are unused. These files may be 



+modified 


-modified 

+Modified 

-sort 

+unused 
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-All- 

+directories 

-directories 

+age__sort 

+Size_sort 

+reverse_sort 

+size 


+blocks 


c -columns 


-columns 


+file_list 


+horizontal 

+verbose 

+exeeutable 

-executable 

+elear_screen 

w -width 


Inline Jength 


recoverable if they were recently deleted. 

- Don’t list all files. Files beginning with a character will be 
excluded from the file list. 

- Directories on. List only directory files in the output. 

- Directories off. Do not include directory files in the output. 

- Sort by age (most recent first) rather than by file name, 

- Sort by file size (largest first) rather than by file name. 

- Reverse the sort order to get reverse alphabetic, oldest first, or 
smallest first, as appropriate. 

- Show file sizes. This mode is active whenever verbose mode 
is turned on. If verbose is off, then the file size display must 
be selected with this flag. 

- Show block counts. If file sizes are being displayed, this flag 
will cause the file size to be displayed in blocks rather than 
in bytes. 

- Used to manually set the number of columns in the output. 

If the number of columns is set to a large number, then a 
stream of file names will result. A column setting of 0 has no 
effect. 

- Turn all multi column output off. This forces the output to be 
displayed as one column. This has the side effect of asserting 
horizontal output mode, which forces the after each file 
name is output. 

- Display a list of files, excluding any directory files, modified 
notation or file sizes in one column. This command is 
synonymous with "Is -v -c -d +h" and is used as a short hand 
notation for it. This option is useful to prepare lists of files 
for other commands to process. Executing "Is +f p=*.[ch]" is 
a quick way to get a list of all the source files in a directory. 

- Horizontal file list. This causes the file names to be listed 
across the columns rather than down the columns. 

- Display the output complete with directory name, file sizes 
and a usage summary. 

- Executable files on. List only executable files in the output. 

- Executable files off. Do not include executable files in the 

output. 

- The screen is cleared before the directory is displayed. 

- Used to manually set the width of the columns in the 
output. Changing the column width causes the number of 
columns displayed to also be recalculated. This recalculation 
can be supressed by manually setting a column count with 
the c= option. A column width of 0 is quietly ignored. 

- Used to manually specify line length. This is useful for 
sending the output of this command to a printer that may 
have a 132 or 240 character line. Also useful for squeezing 
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+tx_time 


b =baud rate 


p -{^pattern 


See Also: 

CD 

DIR 


the output onto a 40 column screen if necessary. 

- Used to cause the transmission time of a file to be displayed. 
The default baud rate used for this calculation is 1200 baud. 
The b= option can be used to specify a baud rate. While Ms 
mode is active, directory display is turned off. 

- Used to manually set the baud rate used for transmission 
time calculations* If a b= option is specified on the command 
line, the time display mode is automatically selected without 
+t having to be specified. 

- List all files matching the pattern described. This pattern 
match is applied to die files that make it through die flag 
settings. For example, if the -d option is set, even directory 

files which match the pattern will not be included in the 

output. The ’ A? character can be used to negate die pattern 

match. Character ranges can be specified in the form [a-e]. 
This would be expanded to [abcde] for matching purposes. 
Multiple ranges and die ’ A? option also work. Filename 

patterns can be any valid filename, with the following 
"wildcard” characters: 


* will match any character, or run of characters 

? will match any one character 

[ccc] will match any of the characters in the brackets 

Some examples of filename patterns are: 


p=* * 

any 

p=*.[ch] 

any 

p=?a 

any 

p=[a»e]* 

any 

p= A *.o 

any 


file with a dot (.) in it. 
file ending in ’c’ or ’h’ 
two character filename ending in ’a’ 
file starting with ’a’,’b’, ’c’, ’d’ or ’e’ 
file which doesn’t end in ’.o’ 


FILES 

PWD 
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MAKE - Maintain and recreate files 

Syntax: 

make [target I option 1 macro jdefinition] * 

Options: 


f-filename - Use filename as the description file. The default is makefile 
or Makefile in the current directory. 

-{-print - Print the complete set of macro definitions, rules and 

dependency descriptions. 

+ignore_errors - Ignore error codes returned by invoked commands. 

-verbose - Do not print command lines before executing. 

-execute - Print all command lines (even those beginning with an "@") 

but don’t execute them. 

-{-touch - Change the dates of the target files instead of executing the 

usual commands. 

-{-unconditional - Ignore the file dates (assume every target file and dependent 
is out of date) and recreate everything, 
d -directory - Change directory to directory before doing anything else. 

This allows MAKE to be used recursively in other 
directories. 


+debug - Debug mode. Print out detailed information on files and 

times examined. (This is usually used when the description 
file is not performing as desired). 


All other arguments are treated as target files to be "made", unless they contain 

an "=" sign, in which case they are a macro definition (see the section on 
macros for more details). 

Examples: 


make 

make -e f=my_makefile 
make +t x.o y.o core 

Description: 
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MAKE is used to maintain up-to-date versions of target files by ensuring that all of 
the files on which the target file depends exist and are up-to-date. If any of the 
dependents have been modified more recently than the target file, it is (re)created 
using specified commands or internal rules. MAKE performs a depth-first search 
of the dependencies, examining the date and time that the files were last modified. 

Usage 

MAKE reads a description file that defines the way that the components of a 
program depend upon each other, and what commands must be executed to 
recreate each component. 

If no f -file option is given, the files makefile and Makefile in the current directory 
are tried in order. 

Description Files 

A description file consists of the following information: 

- macro definitions 

- dependency information 

- executable commands. 

The basic form of a simple description file is: 

dependency line 
command line 
command line 


This may be repeated as many times as needed. 

The syntax of a dependency line is one or more target file names, followed by a 
colon (:), followed by the names of zero or more files on which the target(s) 
depend. This can be expressed as: 

target [target]* : [dependent]* 

Some examples of dependency lines are: 

x.o : x.c header Ji /dir/file.h 
core : a.o b.o c.o 
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If you wish to use a full path name for one of the targets, the colon between the 

drive and path must be escaped using a backslash (\), such as: 

3\:/user/„. % dependents 

Zero or more command lines follow dependency lines. Command lines consist of 
a tab, optionally followed by an "@" sign or a -or both (in any order), followed 
by an executable shell command. The printing of a specific command is 
suppressed if the command line begins with an ”@ M sign, unless the -execute op¬ 
tion is specified. MAKE normally terminates if any command returns an error 
code, unless the 4gnore_errors options is specified, or the command line begins 
with a The oris not part of the command. 

The syntax of a command line can be expressed as: 

tab[@\-]* commandJine 

Because each command line is passed to a separate invocation of the shell, care 
must be taken with certain commands (e.g. cd and shell control commands such as 
path) that have meaning only within a single shell process. The effects of these 
command are forgotten before the next line is executed. However, you can place 
multiple commands on the same line, separated by a semi-colon (;). For example: 

cd my_dir;cc myprog 

All commands on a line such as the one above, will be executed by the same shell, 
so cd and path commands will take effect, for the other commands on that line. 

The comment convention is that a sharp (#) and all characters on the same line 
after a sharp are ignored. A comment cannot be placed at the end of a command 
line. Blank lines and lines beginning with a sharp (#) are totally ignored. If a 
noncomment line is too long, the line can be continued by using a backslash (\) as 
the last character of the line. In that case, the backslash, the new line, and all 
following blanks and tabs are replaced by a single blank. 

A target can appear on more than one dependency line, with the dependents on the 
additional lines adding to the previously defined dependents. Although not as 
useful, any commands related to the additional dependency lines also add to the 
end of the list of previously defined commands for that target file. 
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An example of this is: 

x.o y.o: a.h 
. x.o: b.h 

which is the same as: 

x. o: a.h b.h 

y. o: a A 

The following description file example says that printjsetup depends upon three 
object files: printsetup.o, smalLo, normaLo; each of the objects depend upon 
their source files and, in addition, print setup.o and small.o depend on the header 

files setup A and printA. 

# Description file for printjsetup program 

printjsetup: printjsetup.o small.o normaLo 
cc print setup.o small.o normaLo 

printjsetup.o: printjsetup.c setupA printA 
cc -c printsetup.c 

smalLo: small.c setupA printA 

cc -e small.c 

normaS.o: normaLc 

cc -c normaLc 

To make the file printjsetup, assuming that the above description file is in a file 
with the name makefile or Makefile, you would enter: 

make print setup 
or 
make 

The second example will use the first target mentioned in the description file 
(printjsetup). It is also possible, though less common to type: 

make smalLo 

to only remake a single object file. 


Utilities 


[MAKE] 



MAKE 


As more features of MAKE are described, you will be shown how to simplify this 
description file. 

Macros 

MAKE has a limited form of macro processing that includes string substitution. 
Macros are defined in the description file by: 

inacro__naiiie = valiie_string 

Macros may also be defined in the argument list passed to MAKE. Any argument 
that contains an "=" is assumed to be a macro definition, with the exception of the 
f- and d= options. Special care must be exercised when defining macros in the 
arguments. The following guidelines should be followed: 

1) No spaces are allowed between the first 5 = 5 and the macro 

name or the value. 

2) When the macro definition includes imbedded blanks, the 

entire macro definition should be enclosed within quotes. 

3) The macro name is all of the characters before die first 

and the value is all of the characters after the first 


For example: 

make CC=cppo "LFLAG=+v i=mylib Vf 

This command will define two macros CC and LFLAG with the following values 
"cppo" and "+v l=mylib". 

Macros may be used in any of the dependency, command or macro definition lines 
(resulting in nesting of macros) and are recognized whenever $(macro_name) 
appears in the input. If the macro name is one character the parentheses are not 
required. The following are all valid macro invocations: 

$(CFLAGS) 

$2 

$(xy) 

$z 

$(Z) 

pe last two invocations are identical. A $$ is a simple dollar sign ($). Care must 
be taken when using macro nesting; recursion (repeatedly nesting the same macro) 
is not tested for. ' 


[MAKE] 


Utilities 



MAKE 


The following is an example of a use of nested macros: 

HEADEES1 = xA yJi zA 
HEADEES2 = aA bA cA 
ALLJHEADERS = $(HEADEES1) ($HEADEES2) 

There are a number of macros built into MAKE which are initialized when MAKE 
is started. They may all be redefined within a makefile or on the command line. 
Most of these initialized macros are used for the transformation rules (discussed 
later), but two of them deserve special attention: CWD and SHELL. 

The macro CWD is initialized to the current working directory in effect after 
MAKE processes its command line options (to give the "d=" option time to take 
effect). It is occasionally useful within command lines. 

The macro SHELL is initialized to the default shell in use by the user. However, 
it may be reset to indicate which shell should be used for interpreting command 
lines when executed. For example, if you are using shell (user interface) other than 
the default shell supplied with QNX, it may not be able to interpret certain 
command sequences (such as "#u" - your userid) used in a particular makefile, 
which expects that you are using the default shell. To condition make to always 
use a particular shell (for example, the QNX default) instead of the user default, 
include a line like: 

SHELL = /cmds/sh 

The previous description file example can now be simplified to: 

# Description file for printsetup program 

OBJECTS = printsetup.o smaiLo normal.o 
HEADEES = setup A printA 

print_setup: $(OBJECTS) 
cc $(OBJECTS) 

prin£_setup.o: print_setup.c $(HEADERS) 

cc -c printjsetup.c 

small.o: small.c $(HEADERS) 

cc -c small.c 

normal.o: normaLc 

cc -c normal.c 
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Invocations of macros in dependency lines are expanded immediately. Macros in 
macro definitions are expanded when used. Macros in command lines are 
expanded immediately before the command is executed. 

A macro that has never been assigned, expands to a null string on invocation. 

Macro Redirection 

In QNX, it is frequently useful to have a list of file names stored in a file (an index 
file). For example, a list of object files to be linked together may be stored in a file 
called ofiles. However, this same list of objects may be needed by MAKE, so they 
can be made before linking. To avoid the need to maintain the list in the index file 
and the MAKE description file, it is possible to have the contents of a macro read 
from a file. The syntax for this is: 

macro = ©filename 

An example is: 

OBJECTS = ©ofiles 

Suffixes. Implied Dependencies and Internal Macros 

The only thing MAKE knows about file name suffixes, is that they begin with a 
To compensate for this lack of understanding, it has an internal table of 
suffixes for files which are frequently used with MAKE. As MAKE examines the 
file dates and times, it also matches die suffixes in the table against the file names 
to try and extrapolate from the dependencies in the description file to other 
(implied) dependents. The information extracted and built is placed in a series of 
internal macros. 

The suffix table has the form of a dependency line where the target is .SUFFIXES 
and the dependencies are the suffixes. Naturally, there are no command lines for 
.SUFFIXES. 

The default suffix table looks like: 

.SUFFIXES: .0 .c .c~ .h ,h~ .a .a~ .y .y~ .b .b^ .exe 


[MAKE] 


Utilities 



MAKE 


where the suffixes represent: 

.0 Object file . ■ 

.c C source file 

.c^ C source file in an archive 

Ji Header file 

.h^ Header file in an archive 

.a Assembler source file 

.a^ Assembler source file in an archive 

.y Yacc-C source grammar 

.y** Yacc-C source grammar in an archive 

.b BASIC source file 

Jr* BASIC source file in an archive 

.exe DOS .exe file 

As QNX supports more languages, this table will be extended. MAKE will list the 
internal tables, macros, etc. if make +p is entered. 

Suffixes ending with a tilde (~) exist to support a source code revision control 
system, that may appear in the future. 

The order of the suffix list is important, since the list is scanned from left to right. 
New suffixes can be appended to the table placing an entry for .SUFFIXES in the 
description file, such as: 

.SUFFIXES s .xyz ■ ■ 

/This will add the new suffix ".xyz" to the usual list. A .SUFFIXES line without 
any dependent suffixes deletes die current list. It is necessary to do this to remove 
suffixes from the table, or to change the order of search. An example is: 

.SUFFIXES s 

.SUFFIXES:' .0 .c 

By reducing the number of suffixes in the table, it is possible to improve the 
performance of MAKE when working with very large systems. When it is poss¬ 
ible to define new rules, this facility will be useful for adding suffixes for new 
languages which MAKE is not already programmed to handle. 

The current target file name is placed in the macro $@, and the stem (the portion 
of the target file name, less the suffix as found in .SUFFIXES) is placed in $*. If 
no suffix was matched to the target file name, $* contains a null string (""). 
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Once a stem has been identified, in turn, each of the suffixes are concatenated to 
the stem and the resulting filename is matched against the dependents specified in 
the description file, to try to find the name of the "source" dependent. If an explicit 
"source" dependent isn’t found, the same procedure is tried against the file names 
in the same directory as the target file in an attempt to find an implicit "source" 
dependent. If a "source" dependent is found, its name is placed in the macro $<, 
else it will expand to a null string. 

As MAKE checks each of the explicitly stated dependents, it places the names of 
the dependents younger than the target file in the macro $?. 

The following table summarizes the internal macros: 

$@ - The target file name. 

$* - The target stem (the file name less the suffix). 

$< - The "source" dependent (the stem plus a suffix). 

$? - The explicitly stated dependents, younger than the target. 

With the search for implied dependencies and the internally maintained macros, it 
is now possible to reduce the example above to: 

# Description file for printsetup program 

OBJECTS = printsetup.o small.o normal.o 
HEADERS = setup.h print.h 

print setup: $(OBJECTS) 

cc $(OBJECT8) 

print setup.o small.o: $(HEADERS) 
cc -c $< 

normal.o: 
cc -c $< 

Notice that the source file names are never mentioned, but are implied by the 
suffixes. 

When MAKE scans the arguments it is passed, the options specified (with the 
exception of f=, +p and d=, the target names and macro definitions) are placed in 
the internal macro $(MAKEFLAGS). This is for use with hierarchical makefiles. 
See the section on Recursive Makefiles for details. 
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Extensions to $*. $@. and l< 

To the list of internally generated macros, the following related macros have been 
added: $pF), $(*B) 9 $(@F) ? $(@D), $(<F), $(<D). The "D" refers to the directory 

portion of the single letter macro. The "F" refers to the file name part of the single 
letter macro. They are useful for maintaining source and objects in different 
directories, or in conjunction with hierarchical makefiles, as in: 

$(MAKE) $(MAKEFLAGS) d=$(<D) $(<F) 

An alternative to the above, would be the line: 

cd $(<D);$(MAKE) $(MAKEFLAGS) $(<F) 

Both of these examples will cause MAKE to change directory to the directory 
$(<D) before reading the description file and making the target $(<F). The second 
example (with the cd command) will temporarily change directory at the shf 11 
level. The current working directory will revert to the original directory MAKE is 
being run in at the end of die line. See the section on Recursive Makefiles for 
details on MAKE invoking MAKE. 

Transformation Rules (Implied Commands) 

If a "source" dependent (the macro $<) was identified and there are no commands 
associated with the current target (the macro $*), a transformation rule is selected 
based on the suffixes of the target and dependent file names. The name of the rule 
is made by concatenating the suffix of the source to the suffix of the dependent (i.e. 
the rule to transform a .c file to a .o file is .c.o). 

Rules have the syntax of a dependency line and command line(s), where the target 
name is the rule name and the command line(s) are the commands to be executed if 
the rule is invoked. Naturally, a rule has no dependencies. MAKE version 2.1 and 
beyond will allow rules to be redefined and new rules to be created, but this facility 
is not yet supported. 

The .c.o rule is expressed as: 

.c.o: 

$(CC) $(CFLAGS) -c $< 

This means, execute the command in the $(CC) macro (default: "cc") with the 
arguments in the $(CFLAGS) macro (default:""), as well as the argument "-c" 
(don’t produce a core file) on the file whose name is in the macro $<. 
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An example of a complex description file follows. This is the file used to maintain 
the MAKE command. The only transformation rule it uses is the .c.o rule 
described above. The file contains: 


# 

# Create the make command in the current directory 

# 


CFLAGS = +optimize 


SOURCES= 
HEADERS= 
OBJECTS = 

INSDJR = 


main.c make.c misc.c read_file.c input.c rules.c definitions.c 
manif.h struct.h extern.h 

main.o make.o misc.o readfile.o input.o rules.o definitions.o 

/crads 


core: compiledate.o 

$(LD) l(LDFLAGS) $(OBJECTS) compile_date.o 

@patch core +p 


install: 

copy core $(INSDRIVE)$(INSDIR)/make 

print: $(SOURCES) $(HEADERS) 

list w=80 +r $? 
chattr $@ +d s=+m 

compile date.o: $(OBjECTS) 

$(CC) +p -c $< 

$(OB JECTS): $(HE ADERS) 

make.o: /lib/task msgs.h 

misc.o: /lib/io.h 7lib/!fsys.h /lib/dev.h 

rules.o: /lib/accounth /lib/task_msgs.h /lib/systids.h 


[MAKE] 


Utilities 



MAKE 


The following output results from typing make in a directory containing only the 
source and description file: 

MAKE: cc -c definitions.© 

MAKE: cc -c rules.© 

MAKE: cc -c input.c 
MAKE: cc -c readfile.c 
MAKE: cc -c misc.c 
MAKE: cc »c make.c 
MAKE: cc -c main.c 
MAKE: cc +p -c compiledate.c 

MAKE: cc main.o make.o misc.o readfile.o input.o rules.o 
definitions.© compiledate.o 

Although none of the source files were explicitly mentioned in the description file 
as being dependencies of the target core, MAKE found them using its suffix rules 
and issued the needed commands. The printing of the patch core +p command 
was suppressed by an "@" sign. 

The "print" and "install" entries in the description file are useful maintenance 
sequences. The "print" entry prints only the files changed since the last make 
print command. A short file print is maintained to keep track of the time of the 
printing. The $? macro in the command line then picks up only the names of the 
files changed since the file date and time of print was changed (via chattr +d). 

In the "install" sequence, MAKE can be installed into different directories or on 
specific drives as follows: 

make install INSDRIVE=1: 
or 

make install INSDIR=/free 
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The following is a listing of all the internal macros and default rules: 

# LIST OF SUFFIXES 

.SUFFIXES: .0 .c .c~ Ji .lr* .a .a~ .y .y~ .b .b~ .exe 

# PRESET VARIABLES 

MAKEFLAGS=-e 

MAKE=make 

YACC=yacc 

YFLAGS= 

LD=cc 

LDFLAGS= 

CC=cc 

CFLAGS= 

AS=asm 

ASFLAGS= 

GET=co 

GFLAGS= 

CWD=3:/man/iitil 

SHELL=/cmds/sh 

# INTERNAL RULES 


.c.o: 

$(CC) $(CFLAGS) -c $< 

X $(GET) $(GFLAGS) $< 

$(CC) l(CFLAGS) -c $*.c 

rm $< 

.h-Jis 

$(GET) $(GFLAGS) $@ 

.a.o: 

$(AS) l(ASFLAGS) $< $@ 

’ a *°* $(GET) l(GFLAGS) $< 

$(AS) l(ASFLAGS) $< $@ 

rm $< 

s y.c: 

$(YACC) $(YFLAGS) +d $< 

$(YACC) l(YFLAGS) +d $< 
$(CC) $(CFLAGS) -c $*»e 
rm $*.c 
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.y~.o: 

$(GET) $(GFLAGS) $< 
$(YACC) l(YFLAGS) +d $< 
$(CC) $(CFLAGS) -c $*.c 
rm $*«c $< 

.b.o: 

$(CC) l(CFLAGS) -c $< 

.b^.o: 

$(GET) $(GFLAGS) $< 
$(CC) $(CFLAGS) -c $< 
rm $< 

.o.exe: 

$(GC) $(CFLAGS) +D $< 

.c.exe: 

$(CC) $(CFLAGS) +D $< 

.c~.exe: 

$(GET) $(GFLAGS) $< 
$(CC) $(CFLAGS) +D $< 
rm $< 


This table may be reproduced, with the output appearing on the standard output, by 
the following command: 

make +p f=$null 

Given all of the above capabilities, the description file for the print_setup program 
can be reduced to the following: 

# Description file for print setup program 

OBJECTS = printsetup.o small.o normal.© 

HEADERS =setup.h print.h 

printsetup: $(OBJECTS) 

cc $(OBJECTS) 

print_setup.o smail.o: $(HEADERS) 

Because normal.o is dependent only on its source file, it needn’t be mentioned as a 
target anywhere in the description file. Its source file will be found by the use of 
the suffix table and will be made (if necessary) using the transformation rules. 
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Alternate Implied Source Directories 

By default, MAKE expects that the source dependent be in the same directory as 
the target. However, this is not always the case. It is sometimes useful to have the 
source "scattered" across a number of directories and have MAKE search these 
directories to find the source. The alternate directories are specified using the 
pseudo-target .ALTJDIRS, as follows: 

.ALTDXRS: ver2.0 verl.2 verl.l verl.O 

Placing the above line in your makefile will cause MAKE to search the alternate 
directories in specified order for an implicit source dependent after first searching 
the directory of the target. This example will give you some ideas as to how 
MAKE may be used for simple version control. (The current directory is the most 
recent source. If the source isn’t here, start looking back at the earlier version 
archives). 

If you are working with C source in the above scenario, you must tell the CC 
command where to place the object files it compiles (they default to the same 

directory as the source). If you specify the following C compiler flag: 

0=$(@D) 

for example: 

CFLAGS = 0=$(@D) 

then when C source is compiled to object, it will automatically be placed in the 
"target" objects directory (usually the current directory). 

Recursive Makefiles 

Another feature of MAKE is the ability to have make invoke itself. This is useful 
if the description file is too complicated (or too large). If a command line contains 
the sequence "$(MAKE) M anywhere, the line will be executed even if the -execute 
flag is set. Since the -execute flag can be carried across invocations of MAKE via 
the $(MAKEFLAGS) macro, the only command that will actually be executed is 
the MAKE command itself. For testing purposes, make -e can be executed and 
everything that would have been done will be printed, including output from lower 
level invocations of MAKE. 

An example of a command line invoking another level of MAKE is: 

$(MAKE) $(MAKEFLAGS) f=makefile2 
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It is also occasionally useful to have a target dependent on a file which is 
maintained by a makefile in another directory. The usage of the d= option to 
facilitate this is described in the section on Extensions to $*, $@ and $<. 

See Also: 

cc 
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MKBIR - Make directory 



mkdir directory [size] 



size - Initial size of directory (default: 10 entries) 



mkdir dirl 

mkdir 3:/cmds/backup 20 

MKDIR will create a directory with the given name. If a simple name is given, the 
directory will be at the current directory level. If the name starts with a slash (/), 
then the complete pathname from the root of the file system is specified. A drive 
number followed by a colon (:) can precede the pathname which forces the 
directory to be made on the given drive. Otherwise, the directory will be made on 
the first drive it finds which matches the prefix. For instance, the second example 
above will create a directory "/user" on drive 3. Without the "3:", the directory 
would be created on the first drive searched, which is often a ramdisk. 

Space is initially reserved for 10 files if no size is given. Note that directories, like 
files, will grow so that this size parameter does not limit the size of a directory. 
Directories can contain any number of files, but may become fragmented if the 
initial size is not made large enough which often implies a speed penalty when- 
opening files. 

mkdir 2:/cmds 100 

See Also: 

DREL FREL RMDIR RM 
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MORE - Display a file or stdin by pages 

Syntax; 


more [<stdin \ filename I x=filename]* [options]* 
options: +numbers +raw -tab 

Options: 

filename - Name of file to print (default: keyboard) 
x=filename - Name of index file that names files to browse 
+numbers - Display line numbers 

+raw - Don’t interpret escape sequences 

-tab - Don’t expand tab characters 

Description: 

MORE is a file browser that uses the high speed terminal display routines to 
display a file on the console. While the file is being viewed on the console, it is 
also being stored in a large, dynamically allocated buffer. This buffer allows text 
that has scrolled off the screen to be "rolled back" for later review. Note that only 
the last 60K ( approximately ) of viewed text can be reverse scrolled. 

After the first page of output has been displayed, various commands are available. 
The most used of these commands would be those that cause the display of more 
text to be started and stopped. This can be done a number of ways. The space bar 
can be pressed to start and stop output, the XON / XOFF ( A S and A Q ) characters 
can be used, the space bar, or the large plus key. Once the scrolling has been 
stopped, a menu appears at the bottom of the screen to prompt for further 
commands. 

FI or - These keys can be pressed to display a help menu. 

Left and Right cursor keys - These keys allow the text to be scrolled to the left and 
right. 

Up and Down cursor keys - These keys allow forward or reverse scrolling a line at 
a time. New text from the file will be loaded and displayed if viewing past the end 
of buffered text is attempted. 
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Control Up and Down - Depressing the control key while typing the up or down 
arrows will cause the text to jump up or down by four lines. This is intended to 
mimic the action of the same keys in the QNX editor. 

PgUp and PgDn keys - These keys allow viewing text in a forward or reverse 
direction a page at a time. New text from the file will be loaded and displayed if 
viewing past the end of buffered text is attempted. 

Home - This key restarts the display at the top of the buffered file. If the amount of 
text buffered has exceeded the buffer size, then the earliest text still in the buffer 
will be used as the starting point for the display. 

End - This key causes the text in the last page of the buffer to be displayed. Only if 
the actual end of file has been reached, will the text at the end of the file be 
displayed. If the end of file has not yet been reached, pressing the space bar will 
cause output to resume at that point. 

V - This key causes the currently displayed page to be redisplayed with line 
numbers along the left column. 

Digits 9 1 9 through 9 9 9 cause the text to be advanced by the corresponding number 
of lines. 

9 F 9 or 9 / 9 - MORE will prompt for a pattern to find within the buffered text. Once 
the text has been found, the screen will be updated such that the located text 
appears in the top line of the screen. Executing the find again will cause the next 
pattern to be found. The pattern describes a template which the filename must fit. 
Two special wildcard characters and ’?’ may be used in defining the pattern. 

9 * 9 will match any run of characters (or none at all), whereas 9 ? 9 will match any 
single character. In addition, any characters enclosed in square brackets ([ ]) 
indicate that any one of those characters will match. The escape ’V character can 
be used to match the wildcard characters. A 99 character can be used as the first 
character in the string to indicate that all names NOT matching the pattern are to 
return a match condition. 

9 r 9 - This key toggles "raw" mode on or off. MORE will by default attempt to 
display escape sequences in a file with the appropriate display attributes. For 
example, an Escape followed by a ’<’ character would turn BOLD on. See the 
operating system manual for other escape sequences. With raw mode turned on, 
the actual escape characters will be displayed rather than interpreted into the 
appropriate visual modes. 

Tab or 9 t 9 - This key toggles the display of tab characters in the viewed text. 


[MORE] 


Utilities 



MORE 


Escape key, V or ’x’ - These keys exit the file browser. 

Enter key or ’q’ - These keys advance the file browser to the next named file if 
multiple files were specified. If only one file was specified, this key exits the 
browser. 

The ’z’ key flips the screen through the various screen resolutions. For example, on 
an system equipped with an EGA display card and the appropriate graphics driver 
mounted, the zoom command will toggle the screen between 80 by 25 line mode 
and 80 by 43 line mode. When an exit from the MORE command is. performed, the 
original display mode is automatically reselected. 

Note: Browsing multiple files from a single invocation of MORE causes the 

displayed line numbers to count from one for the first file and continue from that 
point for each successive file. 

See Also: 

p 

CAT 
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MOUNT - Mount a new disk drive or new memory 

Syntax: 


mount, disk drive[d~driver num\ [load file] [h-v] 

[s =size] or [pa -osjype] 

[h =heads t-tracks n-sectors! track] 

[p=physical_drive] [c=ctl_addr\ [i ^interrupt] 

[u=user_data] [w=write_precomp_cyl] 

[+large_xtnts] [-large_xtnts] 
mount cache d-drive_number s=size[k] 
mount xcache s=size[k] 
mount bmcache d =drive_number 
mount ramdisk drive [loadjile] [s=size] [-v] [+v] 
mount remdisk drive m=node_number d-drivejmmber 
mount console [device jiumber] newjiame 
mourn; lib load Jile [+v] 
mount file loadjile [+v] 
mount debug [load Jile] [+v] 
mount mem m-segment s=size 
mount float 
mount 

Options: 

load Jile - Specifies the name of a disk driver load file which can be used 

to control this drive. If none is specified, the floppy drivers 
will be used. In the case of MOUNT DEBUG, loadjile is 
the name of the debugger to use which defaults to 
"/cmds/sys.debug". If MOUNT FILE or MOUNT LIB is 
used, then loadjile is the name of the file to load, 
s =size - Specify the storage capacity of the disk if different from the 

default value specified in the driver load file. This option is a 
short form useful when mounting special floppy diskettes. It 
is also used when mounting special memory. Always use the 
h=, t= and n= options (and never s=) for hard disks. The 
letters "k", "K", "m", M", Y or ’T may follow the size to 
indicate sizes in Kbytes, Megabytes or Tracks. Otherwise, 
the number refers to the number of 512 byte disk blocks (or 
16 byte memory blocks for MOUNT MEM). The postfix M 
should be avoided since it provides only a very course 
resolution of size. The postfix T refers to the number of 
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tracks under one head. It is often referred to as cylinders as 
well. 

m-segment - Starting segment of new memory being added, (top 16 bits 
of 20 bit memory address). This will not work in protected 
mode. 

p -drive - Use this physical drive rather than drive 1. 

pa =os_type - Use the partition information to determine the correct offset 

and size to mount the disk. You may still need to specify the 
correct t=, h= and n=. The os_type may be the characters 
qnx, dos or a number between 1 and 255. The characters 
qnx are the same as the number 7 and dos is the same as the 
number 1. To use this option you must have set up a partition 
using the FDISK command. 

c =ctl_addr - I/O control address used by driver. This option will rarely be 

used since this information is in the supplied driver, 
i ^interrupt - Interrupt used by driver. This option will rarely be used since 

this information is in the supplied driver. 

-verbose - Don’t display any messages. 

+verbose - Display extra information about where the driver or file is 
mounted. 

u=user_data - Internal use. 

+large_xtents - used with QNX versions < 2.06 
-large__xtents - used with QNX versions < 2.06 
w -writejprecomp_cryl 

- used as options to specify your own user data space when 
writing a disk driver. 

Examples: 


mount disk 2t=80 h=2 n=8 - Mount drive 2 as a -640K floppy, 

mount disk 2 s=640k - Also Mount drive 2 as a 640K floppy 

mount disk 3 /drivers/disk.xt pa=qnx 

- Mount drive 3 as a hard disk using the 
driver found in the file "/drivers/disk.xt". 
Mount the QNX partition. 

mount ramdisk 5 s=128k - Mount drive 5 as a high speed memory 

disk with 128Kbytes of storage (data is 
stored in RAM instead of on a disk). 
(Remember to DINIT the ramdisk before 
using) 

mount mem m=D000 s=128k - Add 128K of memory starting at hex 

address DQOO. 

mount debug - Load the system debugger into memory, 

mount console $con2 - Mount another console 


mount xcache - Mount a 2k extent cache (default) 

mount cache d=3 s=48k - Mount a 48k cache on disk 3 
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mount bmcache d=3 - Mount a bitmap cache on disk 3 

mount lib /config/qdb.slib - Mount a shared library 

mount float - Mount a floating point library 

mount - Query mounted disks and devices 

Description; 

MOUNT allows the user to add new disk drives and custom disk drivers into the 
system. In addition, memory which is not normally recognized when the system 
boots may be included. The MOUNT command may also be used to load the 
system debugger into memory, or to load any core file into memory. 

If MOUNT is executed without any arguments it will print out what disks are 
mounted in the system, all devices which are present, and any mounted libraries. 

When QNX boots for the first time, it assumes that the setting of the DIP switches 
within the PC correctly indicate how many floppy drives are connected to the 
system, and how much memory is installed. All floppies are initially assumed to be 
the same size as drive 1 unless you are on an AT, in which case the setup informa¬ 
tion in the CMOS ram is used. MOUNT can be used to change the ’’sizes" of the 
remaining disk drives if they differ. As in the first and second example, the number 
of disk blocks which can be stored on a particular drive can be changed. Only 
users which have a non-standard disk drive need to remount their floppy drives. 

In the case of a floppy, MOUNT provides two pieces of information, 

1. The physical characteristics of the floppy drive. This consists of two 
parameters, the number of tracks (40 or 80) and the number of heads (1 or 2). 
The number of sectors/track is a function of the floppy diskette, NOT the 
drive. 

2. The default diskette format to be assumed for NON-QNX diskettes and QNX 
diskettes formatted with early versions of the FDFORMAT command (QNX 
1 . 1 ). 

The FDFORMAT command places a table in block one of the diskette which 
describes how the diskette was physically formatted. This information will always 
override that specified by the MOUNT command. In the case where a drive is 
mounted with 80 tracks and a diskette with 40 tracks is inserted (which contains an 
override table) the system will perform double stepping to correctly read the 
diskette. 

Disk drives other than floppy disks require that a special driver be written to 
handle them. The MOUNT command can be used to include these drivers into the 
operating system. Special disk drivers are normally found on the boot disk under 
the directory /config. 
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The MOUNT command allows a user to create up to 15 logical disks. Only the 
first 8 may be real physical disks. The others may be REMOTE or adopted disks. 
For example, the filename "3:/tmp/test" is found on LOGICAL drive 2. 

A hard disk can be partitioned into several logical volumes. The first logical 
volume on the hard disk must be mounted first, specifying the name of a disk 
driver file. Subsequent logical volumes on that physical disk can then be mounted 
by specifying that the same driver is to be used (d=). The following will mount a 
QNX and a DOS partition. The DOS partition would be accessed by a QNX-DOS 
file system task (DFS). 

mount disk 3 /drivers/disk.xt pa=qnx 
mount disk 4 d=3 pa=dos 

If a driver is capable of supporting more than one physical drive, then the p= op¬ 
tion can be used to force a particular physical drive to be used. For convenience, 
the "MOUNT DISK" form of the command with no driver specified will use the 
floppy driver, implicitly using the same physical drive as logical drive. Thus 
"mount disk 2" will mount a logical disk 2 on physical floppy drive 2. 

The mount mem form of the command is useful in systems where non-standard 
memory cards are being used which may require some initialization before being 
included into the system. In systems with large amounts of memory, the system 
may take a long time to power-up due to the automatic memory check which is 
performed by the firmware. Some people prefer to set the DIP switches to indicate 
some smaller amount of memory which reduces the time required for power-up. 
The MOUNT command can then be used to install the extra memory into the 
system. However, it is recommended that if this practice is followed, regular 
memory diagnostics should be performed to safeguard against memory failure. On 
8088 based PCs or XTs, it can be useful to install an extra 128K of ram above the 
video card (at D000) and an additional 64K just below the video card (at A000) 
for a total of 832K (640K + 128K + 64K). Many PCs have this RAM already 
installed on the motherboard, just waiting to be used. The commands 

mount mem m=d000 s=128k 

mount mem m=a000 s=64k 

will "mount" this memory into QNX, ready for use by tasks or ramdisk. 

The mount debug form of the command is used to load the system debugger into 
memory. The name of a different debugger file may be given as an option. 
Memory will be allocated for the debugger which will remain resident in memory. 
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The mount file and mount lib form of the command are provided to allow user 

compiled and linked programs to be loaded into a block of memory which is 
allocated by the operating system. How the file is mounted depends on the first 
byte of the linked loadfile. The LINKER will by default create loadfiles with a first 
byte equal to 1. This byte can be changed with the PATCH utility. MOUNT 
interprets this byte as follows: 

1 : Common Code and Data (invalid in ATP) 2 : Not used 3 i Data Only 4 : 
Code Only 5 : Common Code and Data (CS:0000 = DS) 6 : Split Code and Data 
(CS:0000 = DS) 

Type 4 is recommended for mounted libraries consisting of pure code (only seg 1 
used in the assembler). Type 6 is recommended for libraries requiring local data 
(MOUNT will put the data segment to use in byte 0000 of the code segment). The 
+verbose option causes MOUNT to display the memory segments it has allocated 
for loading. 

Mounting a cache on a disk will usually speed up accesses to that media. A good 
size for a cache is 48K. Mounting an xcache will cause the file system to cache the 
linkage information which connects the extents within files. As a rule of thumb, 
each xcache entry requires 16 bytes. Thus, only a few Kbytes of xcache can store 
many extent headers. The FILES command will display how many extents each 
file has, allowing you to judge how large an xcache might be useful. Xcache can 
significantly increase performance for large data base files. 

Normally the MOUNT command will be used in system initialization, and may be 
conveniently included into the file 'Vconfig/sys.mit” which is automatically 
executed when QNX is booted. 

Only SUPER users can use the MOUNT command with options. 

See Also: 

FDFORMAT SEARCH 

FDISK SH 

NACC STTY 

PATCH 
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MSORT - Merge sort utility 


msort [file ] [options]* 

Options: 


i=field[field]* 

l=maxjines 

+descending 

+replace 

r=output_file 
p= directory 


•verbose 


Define sort fields 

Maximum number of lines to buffer in 

memory 

Sort in descending order 
Replace file with sorted output 
Place sorted output in output file 
Pathname of a directory where temporary 
files are to be placed. The default is the 
current directory. 

Suppress sort and merge phase messages 


Where: 


field is field_offset. field_width 

left column is 0 

Examples: 

msort inventory f=0.10,10.4 +r 

msort data f=10.5,4.3 r=sort_data p=/tmp 

Description: 

MSORT will sort files based on fixed fields in fixed records. Each record (line) is 
terminated by a record separator (hex IE, *\n’ in C programs) and all records 
MUST be the same size. 

The sort is accomplished in two phases. The sort phase reads and sorts the input 
file in large chunks, appending the sorted chunks into two temporary files. The 
merge phase merges die sorted chunks from the two files into larger chunks in two 
other files. This is repeated until only one chunk remains. Unless -verbose is 
specified a dot will be printed as each chunk is processed in each phase. 
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Sorting is based on the ASCII values of the characters in the file. The order and 
definition of the fields is specified with the f= option. The offset is based at zero 
which is the left hand column. The width is based at one which will sort a single 
character. 

The +r option causes the output of the sort to replace the contents of the original 
file. The output may be redirected to another file using the r= option. If neither the 
+r nor r= ootions are used, the output will go to the standard output which defaults 
to the screen. 

The sorted output will normally be in ascending order. This can be reversed to 
descending order by specifying +d. 

The 1= option will limit the number of records MSORT will attempt to buffer in 
memory. It can be used to keep MSORT small at the price of efficiency. If not 
specified, MSORT will attempt to buffer the maximum number of records which 
will result in a data segment of close to 64K. 

During the sort and merge phase, MSORT will create temporary files with the 
names 

MSORT.n.nid.tid 
where: n is 0,1, 2 or 3 

nid is the nodeid of machine MSORT is running on 
tid is the taskid of MSORT 

These files will be removed if MSORT terminates normally. Users with a large 
ramdisk may wish to place the temporary files there to increase performance. This 
may be accomplished using the p= option. 

See Also: 

SORT 
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- Move files 



mv sourceJile destination Jile 
OR 

mv file* directory 



mv *.c /c_source - Move all c files to the directory 

/c_source. 

mv test.c good.c - Rename the file test.c to good.c 



The first form of MV will move a source file to the destination file. This form of 
MV allows the file to be renamed as it is moved. If the directory of the destination 
file is the same as directory of the source file, the file is simply renamed in place. 

The second form of MV will move multiple files to the specified directory. This 
provides a convenient method of moving multiple files in one simple operation. 
The SHELL special characters *, ?, and [...] are useful for selecting the set of files 
to be copied. If the error 

LINE TOO LONG 

is displayed, you will have to restrict the number of files moved and issue one or 
more commands. 

mv *.[co] dir --> mv *.c dir 

mv *oO dir 

The utility WS is also useful for getting around this problem. For example: 
ws "mv @ dir" p=*.[eo] 
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The following two commands achieve the same effect using the two forms of MV: 

mv /test/file /release/file - destination is a file 

mv /test/file /release - destination is a directory 

For all forms of MV, if the directory the source file is in is the same as the final 
directory, then MV acts only to rename the file. If the destination directory is on 
another device (e.g. moving across a network or from floppy to hard disk), MV 
acts by copying the contents of the source file, then deleting it. If the directory is 
on the same device, the file is logically moved, with no data actually being copied. 

See Also: 

CP 
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NACC - Set network access to disks, devices and CPU 

Syntax: 


nacc [cpu] [%device\* [drive]* [+read] [+write] 
[-read] [-write] 

Options: 

cpu » Control access to CPU. 
device - Control access to $device. 
drive - Control access to disk drive. 

-{-read - Allow read access. 

-read - Disallow read access. 

+write - Allow write access. 

-write - Disallow write access. 

Examples: 

nacc cpu -{-write 


nacc 1 $lpt $mdm -w -r 
nacc 2 +read 

Description: 

NACC may be used to control network access to your local disks, devices and 
CPU. If you remove both read and write, then network access will be denied. The 
NACC command only affects network access. It has no effect on requests which 
originate from the local machine. 

Allowing CPU write access allows non super-users to execute tasks remotely on 
your machine. CPU read access is not currently defined. The default at boot time 
is to disallow everything. 

Network access permissions do not apply to super-users (group 255). 


- Allow non-superusers on other 
nodes to execute commands on 
this node. 

- Remove network access from 
drive 1, $lpt and $mdm. 

- Allow network access to drive 2. 
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If a non super-user tries to execute a task on a remote node, he must have 
previously allowed read / write access to his console. This is because his remote 
task will try to access his console from across the network. For example, if the 
command: 

[4] mount 

is executed from node 2, the user on node 2 must first have executed the command 
nacc $con +r +w 

to grant the mount command running on node 4 permission to display its output on 
the user’s console from across the network. 

See Also: 

ALIVE 

MOUNT 

SEARCH 

STTY 


[NACC] 


Utilities 



NET - Query machines on the network 



net [node_id] options* 



node_id 

-clear 

+horizontal 
-{-vertical 
+repeat 
p -priority 
s-nodejd 
Q=node id 


Only display information on this node. 
Don’t clear the screen first. 

Horizontal display option. 

Vertical display option. 

Repeat until a key is typed. 

Priority to run net (used with repeat). 
Start display at the indicated node. 

End display at the indicated node. 


net 
net 3 

net s=6 e=l 5 +v 

net -c +r 



NET may be used to examine the resources of machines connected together in the 
local area network. NET may only be used with networking versions of QNX. 

In the full screen display modes (+h or +v option), many nodes are displayed and, 
if 4 -repeat option is specified, continuously updated on the screen. Pressing any 
key will cause NET to exit from repeat mode. 

The s= option may be used to start the display at a particular node. 

Note that NET will use the TCAP database to define the terminal characteristics 

for full screen mode. If the terminal has not been defined, NET will display: 

Can’t find terminal type (see TCAP utility). 
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You must then define or set the terminal type using the TCAP command. Not using 
the +h or +v option removes the need for the TCAP database. 

NET displays the system resources which are free (out of total available) for each 
node in the network. Free memory and available tasks virtual circuits are displayed 
in all display modes. 

The default, non full-screen mode of NET will also display the QNX version 
number, free memory, CPU speed, number of ttys on that node, number of 
signaling ports, maximum number of open files and the CPU flags for that machine 
(same definition as for the TSK command). 

See Also: 

TSK 

WHO 
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NETBOOT - Service boot requests from the network 

Syntax: 


netboot [options]* & 


+broadcast 
+verbose 
f -bootjile 
T-retries 
s -slow_down 

Examples: 


Broadcast boot packets. 

Print boot requests on the screen. 

Default boot file. 

Number of retries on a network error. 

Pause between dumping boot packets on the network. 


netboot f=os.2.10pcat & 
netboot +v & 
netboot +b s=3 & 

Description: 

NETBOOT accepts boot requests from machines which wish to boot over the 
network. It must be running as a background task on the boot machine before 
another (booting) machine can boot. Upon receiving boot requests it supplies boot 
records to the requesting machines. 

QNX operating system boot image files are kept under the directory /netboot. To 
prevent confusion, the names of the files in this directory have been chosen to 
indicate the operating system they represent. 


os. if.ff r type 


where n.n 
r 


type 


is the version number (eg: 2.1) 
is the release number (single digit 0 .. 9) 
is a hardware machine type 
peat - IBM PC, AT, PS/2 or compatible 
atp - IBM AT, PS/2 or compatible railing in protected mode 
hv - HP Yectra (before the ES or GR series) 
hvp - HP Yectra running in protected mode 
(before the ES or GR series) 
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The following are typical boot files. 

os.2„10pcat - PC or AT, real mode, release 0. 

os.2.16atp - AT, protected mode, release 0. 

The name of the file to boot from is set in a non-volatile ram on your network 
card. If the boot file name in the card is left blank NETBOOT will default to the 
file specified with the f -bootjile option. 

Unless requested, NETBOOT will only boot one machine at a time. If you select 
the -{-broadcast option, NETBOOT will send boot requests to all machines in the 
network. This allows more than one requesting machine to boot in parallel. There 
is a danger in using broadcast. It will place a load on machines which are already 
running and it is possible for a very fast server to overrun the network input buffer 
of a slow machine which is trying to boot. To avoid this you may have to to slow 
down NETBOOT with the §=slow_down option. You will have to experiment but 
we recommend numbers between 1 and 100. The -{-broadcast option should be 
avoided unless you really have a need for it. 

You will probably wish to place this command near the end of the system 

initialization file for the machine acting as the boot server. 
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NETSIZE - Configure Network Size 

Syntax: 


netsize [f=floppy] [h ^harddisk] 



f -floppy - Floppy disk drive to read from. Default = 1. 

Ji -harddisk - Hard disk drive to write to. Default = 3. 



netsize 

netsize f=2 

netsize f=[2]l h=[5]3 

netsize ti=[2]3 

Description: 

NETSIZE is used to configure the size of the network. It does this by prompting 
the user to insert each Boot disk and Network Expansion disk purchased into the 
indicated floppy drive. For each floppy disk inserted, NETSIZE copies the network 
size information to the indicated hard disk. The defaults are to read from floppy 
disk 1 and to write to hard disk 3, but these can be otherwise specified with the 
f -floppy and b-harddisk options. If the local disk drive is not compatible with the 
media (for example, 3.5" and 5.25" disks ), a network remote floppy drive can be 
specified as: 


$ netsize f=[3]l 


This causes NETSIZE to read from floppy drive 1 on node 3 and to write the 
network size information to the hard disk 3 on the local machine. NETSIZE should 
be run such that it writes to the 3 dnetdisks directory on each hard disk in the 
network that a machine will be booting from. 

Every QNX Boot disk is worth 1 node on the network and Network Expansion 
disks are worth various numbers of nodes. NETSIZE makes it possible to to 
combine these various disks into a larger network license. If you currently have a 
10 node network, and wish to add 5 more nodes, all you need to do is to purchase 5 
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more network cards and a network expansion disk which is good for 5 nodes. Re¬ 
running the NETSIZE utility, and inserting the new network expansion disk when 
prompted will automatically upgrade your hard disk to reflect the new network 
size. Rebooting QNX from this hard disk will cause the new network size to take 
effect. 

The BACKUP and TBACKUP utilities will copy the files stored within the 
/netdisks directory but the copied files are not useful for network configuration. 
You should specify that TBACKUP and BACKUP not copy the contents of the 
Inetdisks directory ( at least for the restore ). If you are restoring from a backup to a 
hard disk, you will need to re-run NETSIZE with your various disks to have the 
node boot from its own hard disk and also participate on the network. This also 
protects the network from network workstations booting from floppy disk and 
accessing the network, since only a hard disk boot from a disk where NETSIZE 
has been run can participate on the network. 

For a first time installation, the 3:Inetdisks directory is automatically created by the 
INSTALL utility before it attempts to run the NETSIZE utility. If you are 
manually running the NETSIZE utility it is important that the 3:1 netdisks directory 
be manually created first. Manually creating this directory helps to ensure that the 

local Inetdisks directory will be updated, and not another one on the network. 

If at any time things appear to not work, ZAP the 3:Inetdisks directory on the hard 
disk, use MKDIR to create a new 3:1 netdisks directory and re-run NETSIZE. Also 
run CHKFSYS to reclaim the disk space lost by using ZAP. 

See Also: 

Network Installation section of the QNX Manual 
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NETSTATS - Display network statistics 

Syntax: 

nets tats [options]* 

Options: 

m=node - The node whose statistics you wish to query. The default 
is your local node. 

+clear - Clear the statistics after returning their current values. 

+report - Generate report style output 

+all_nodes - Display statistics of all nodes on the network. 

+monitor - Enables monitering of network, 
o -offset - Offset in minutes for displaying logged information. 

dl=dd-mon-yy - Start date for displaying logged information. 
62=dd-mon-yy - End date for displaying logged information. 
tt-hh:mm:ss - Start time for displaying logged information. 
t2 =hh:mm:ss - End time for displaying logged information, 
d -monitor__depth 

- Monitor sample size. Default is 1000 samples, 
m -monitorjnask 

- Mask of bits to monitor (hex). 

Description: 

NETSTATS will print out network statistics on a node in the network. These 
values can be used to detect network errors and network load experienced by a 
node. Unless you use the -f dear option, the counters used for the statistics will 
continue to increase in size over time. You must be a super-user to clear the 
counters. 

The following information will be displayed: 

Min Packet Queue: 97 

Each outgoing message is placed in an outgoing packet queue. Messages will be 
lost if this queue goes to zero. This field displays the minimum number of free 
entries the queue has experienced. 

Packet Queue Overrues: 0 

Each time the packet queue goes to zero and a message is lost this number is 
incremented. This number should remain at zero. 
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Network Rx Packets: 24,795 

The number of packets transmitted by this node. 

Network Tx Packets: 22,257 

The number of packets received by this node. 

Reconfigurations : 32 

How many times the physical network has reconfigured since your node was 
booted. This value will increase every time a new node enters the network, and 

should not be considered an error. If this value increases when no node enters or 
leaves the network, it could indicate faulty networking hardware or noise on the 
cables (possibly caused by passive hubs). 

Network Tx Errors: 7 

This value indicates the number of packets which were corrupted while 
transmitting, or which were sent to non-existent node-ids. Non-zero values should 
not necessarily be considered an error, since QNX will retry several times. Every 
network reconfiguration COULD cause this value to increase. A poller will cause 
this value to increase every time a non-existent node is polled. 

Network Tx Timeouts: # 

This value indicates the number of times packets were unable to be sent to another 
node which has a working network card, but whose software is not responding. 

This should be considered an error unless a poller is running on your machine. 

Network Tx Aborts: 1 

This value indicates the number of times QNX gave up when trying to transmit a 
packet. This should be considered an error unless the poller is running on your 
node. 

Network Rx Errors: 0 

This indicates how many bad packets were received. This value should always be 
zero. 

Network Rx Duplicates: 0 

This value indicates how many duplicate packets were received and rejected. There 
is a possibility of receiving a duplicate packet whenever a new node enters the 
network, or whenever the network is noisy. Non-zero values are not necessarily an 
error, but could indicate faulty hardware if excessive. 


Network Monitor Mode 

The Network Monitor Mode can be very useful for examining and diagnosing 
your network. It will keep track of a series of events related to your node in rela- 
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tion to the rest of the network. Here is a list of the events which are logged: 
Event Mask Bit 


TXJRetry 

TXFailed 

RXJDuplicate 

RXInvalid 

Reconfig 

RX_Failed 

Timeout 

Netbootbegin 

Netbootend 

NetjolI_fail 

Netj>oll_dowii 

Net_poll_up 


OOOlh 

0002h 

0004h 

0008b 

0010b 

0020b 

0040b 

0080b 

0100b 

0200b 

0400b 

0800b 


Each entry is time stamped. To enable logging, enter the following at the command 
line (or put in your sys.init.nn file ): 


netstats +monitor 


Then at any time in the future, you may query the current in memory log of events 
by entering: 


netstats 


The m~monitor_mask option cap be used to select (mask) which events you wish 
to monitor/log. See the above table for the mask bit definitions. 

The following options can be used for displaying the logged information: 


o-offset 

M=dd-mon-yy 
d2=dd-mon-yy 
tt=hh:mm:ss 
t2 =hh:mm:ss 


See Also: 

NETTEST 
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NETTEST - Check data transmission between two nodes 

Syntax: 

nettest node [min [max]] 

Options: 

node - The destination node to test. You local node is 
always the source. 

min - The minimum number of 16 bit words to send. Default 1. 

max - The maximum number of 16 bit words to send. Default 500. 



NETTEST will send data between your local node and a specified destination node 
checking the data at both ends. To accomplish this, NETTEST creates a remote 
task on the destination node. If you do not specify the minimum and maximum 
number of 16 bit words to send they default to 1 and 500. Messages of random 
size between these two values are generated for the test. 

NETTEST should run without errors for millions of messages. Errors can occur 
when cables are disconnected from machines connected to a passive hub. 

See Also: 

NETSTATS 
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ONTTY - Create task on another tty 

Syntax: 


ontty ttynum command-line 
ontty ttyname command-line. 

• This is a local shell command • 

Description: 

The ONTTY command executes the indicated command on the indicated tty. The 
command is detached from your terminal and inherits your accounting information 
and current directory. After mounting a console you may wish to create a SHELL 
or LOGIN on that console. 

mount console $con2 
ontty $con2 sh 
OR 

ontty $con2 login 

If this command is combined with the syntax of remote task creation, then the 
remote node should precede the ONTTY. You may also specify the node number 
as part of the device name. 

[4] ontty $con2 ed file 

ontty [4]$con2 ed file 

These will create the editor on $con2 of node 4. The editor will attempt to read the 
indicated file using the search order on node 4. 

If you know the device number you may directly reference it. 

ontty 3 login 

See Also: 

MOUNT 
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OSCONFIG - Change operating system parameters 

Syntax: 


osconfig filename [+l-dos]* 

Options: 

filename - The name of the configuration file. 

+dos - Enable the reserving of base memory for DOS 
=dos - Disable the reserving of base memory for DOS 

Examples: 

osconfig 3:/config/sysxfg 

osconfig 3:/config/sysxfg.4 +dos 

Description: 

OSCONFIG allows you to specify a configuration file which lets you change some 
of the operating system defaults such as the number of open files supported. 

An operating system may boot from 1 of three sources. 

L Floppy 
2. Hard Disk 

3* Network 

When booting over the network, the NETBOOT command attempts to open a file 

by the name 

/config/sysxfg.uFi 

where nn is replaced by the node number of the booting machine. If successful, 
the operating system will use the parameters in this file, otherwise it will use it’s 
defaults. 

Booting from disk is a little different. The configuration file must be explictly 
bound into the operating system using the BOOT command. This is specified as a 
c=3 :/conf!g/sys.cfg. #t» option to the BOOT command. You may select any file 
name, however, we suggest you use the same convention as that used by 
NETBOOT. On a single machine you may omit the ".nn". 
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/config/sys.cfg - Single machine. 

/config/sys.cfg.nn - Network machine. 

The sys.cfg file is created and maintained by the OSCONFIG command. For 
example 

osconftg 3:/conflg/sys.cfg 

would create a configuration file for a single non-networked machine, it is active 

for network booting but does not become active for disk booting until you use the 
BOOT command to set it. 

NOTE . 0 When booting from hard disk you should not remove the config file 
name after you have selected it with the BOOT command. You may copy a new 
file on top of it but NEVER remove it (FREE, RM,...) and then create a new one 

even if it has the same name. The BOOT command saves away the absolute 
starting block numbers of each of these files which will change once the file is 
removed. When booting over the network, the NETBOOT command opens the 
file through regular means and this is not a concern. 

See Also: 

BOOT 

NETBOOT 
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P - Print file contents on terminal 

Syntax: 

p [file] [+raw] 

Options: 

file - Name of file to print (default: keyboard) 

+raw - Don’t expand control characters 



P joe 

p picture +r 

p ilici 

Description: 

The P command prints the contents of a file. Output is sent to the standard output. 
If no input file is specified, it will default to the standard input. Any unprintable 
characters will be expanded into \hh where hh is the hex value of that character. 
This expansion can be turned off by specifying the + r option. 

See Also: 

COPY 

. DUMP 
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PACK - Pack a file to reduce its size 

Syntax: 

pack file* [-remove] [-verbose] [-time] 
or 

pack <infile >outfile [-verbose] 

Options: 

-remove - Suppress the removal of input files. 

-verbose - Suppress status messages. 

-time - Retain original file time. Set to current time by default. 



pack *.c - Pack all C files 

in current directory 

unpack *.z - Unpack all packed files 

in current directory 

pack ctext >packed - Pack file "text" and put 

packed file in ’’packed" 



PACK compresses files into a more compact form. Any file can be packed, but 
program source files and text files benefit the most, typically shrinking by 35%. 
Files containing only a limited character set, such as dictionary files, may shrink as 
much as 48%. Packed files look like gibberish and must be unpacked before they 
can be used. 

The unpacker, UNPACK, expands packed files into exact duplicates of the 
original. 

As each file is packed, a of message of the form: 

Analyzing "filename” ... packing... size = 70% of original 
will be displayed. This can be suppressed by specifying the -verbose option. 
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When the first form of PACK is used each file will be replaced by a file with the 

same name and a .z appended. A filename may not exceed 16 characters so you 

should limit the name length of input files to 14 characters. The input file will by 

default be removed. You can suppress the removal by specifying the -remove 
option. 

When the second form of PACK is used it will read from the standard input and 

write to the standard output. In this case the input file will never be removed and 
you have control over the name of the output file. 

The data in the file is treated at the byte level rather than the word level, and can 
contain absolutely anything. The compression is in two stages: first repeated byte 
values are compressed and then a Huffman code is dynamically generated to match 
the properties of each particular file. This requires two passes over the source data. 

The decoding table is included in the packed file, so packing short files can 
actually lengthen diem. Fixed decoding tables are not used because English and 
various computer languages vary greatly as to upper and lower case proportions 
and use of special characters. Much of the savings comes from not assigning codes 
to unused byte values. 

See Also: 

UNPACK 
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P ARK - Park the heads of a hard disk 

Syntax: 


park drive 



drive - QNX drive number of disk to park. 



park 3 - Park heads of dive 3. 



PARK is called to park the heads of a hard disk prior to turning power off the 
machine. A disk with parked heads will have a much smaller chance of being 
damaged should power fail, or if the unit is being moved. 

The PARK utility will determine the actual size of the hard disk and attempt to 
move the heads to the inner-most track of the disk. 

IMPORTANT: The PARK utility remounts the hard disk to position the heads, so 
should only be called when the system is idle. No other users or programs should 
have any open files when PARK is issued. 
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PASSON -Turn on password protection 

Syntax: 


passon 


• This is a local shell command • 

Description: 

The PASSON command will cause the LOGIN command to look for the file 
"/config/pass" and enforce password protection on login. If this file does not exist 
you will be unable to login. Systems that have booted from a QNX network will 
have passwords on by default. 

Once passwords are enabled, they cannot be turned off. 
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Syntax: 

patch file [options]* 

Options: 


o =offset 
b -byte 

s=stack_size - 
+change_user - 

-changejiser - 
+high__load 

-highjoad 

+privileged 

-privileged 
+remote_ok - 

-remote_ok 

+shared 

-shared 

+8087 

-8087 

Examples: 

patch program 
patch core +p 
patch myjprog +s 
patch data o=2 b= 


Specify offset in file to patch (hex). 

Specify new byte at this offset (hex). 

Set the stack size for an executable program. 

Make command ran with effective user 
of user which owns the file. 

Remove change jowner flag. 

Force command to be loaded into high 
memory. 

Remove highjoad flag. 

Make command privileged. 

Remove privileged flag. 

Allow command to be executed on a 

remote node. 

Don’t allow command to be executed 
on a remote node. 

Make command sharable. 

Remove shared flag. 

Indicate that command needs an 8087. 
Pretend that the command doesn’t 
need an 8087. 


Display the current patch status of the file. 

Make the file "core" privileged. 

Make "my_prog" sharable. 

2a 

Patch the 3rd byte of the file "data" replacing it with the byte 
2a hex. 
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Description: 

PATCH can be used to modify the attributes of an executable file or it can be used 

to patch any byte in the file. 

Setting the change_user flag will cause the command to assume an effective user 
number which is the same as the file. If the file is owned by the super-user, then 

the command will ran with super user privileges regardless of who executes it. For 

example, 

patch /cmds/date +c 
will allow anyone to set the date. 

Setting the tiighjoad flag causes the code segment to be allocated at the top of 
memory. Normally code and data are allocated at the low end of memory. This 
flag may be set on tasks which remain in memory for long periods of time (such as 

CLOCK). By keeping these long lived code segments high in memory, memory 

fragmentation problems are reduced. 

Setting the privileged flag allows the privileged system functions to be used. Only 
files which are created by the super-user AND which have been made privileged 
will be allowed access to these functions. The absolute disk block I/O functions of 

DISK JRE AD JB LK and DISK_WRITE_BLK require that the task be privileged. 

Setting the remote ok flag allows a command to be executed on a remote node 
even if remote task creation has be disallowed on that node. This allows informa¬ 
tion programs to be run remotely by a non super-user. 

Setting the shared flag allows multiple instances of this command to be created 
without going to the disk. Instead, the code is shared and any constant data is 
copied form die data segment of an existing task. Each task will still have its own 
data segment. For example, the SHELL and the EDITOR have been made 
sharable. The program must not have have any initialized global variables. 

Setting the +8087 flag will cause the system to refuse execution if there is NOT an 

8087 installed in the system. Any programs which contain 8087 opcodes will. 
automatically cause this flag to be set. However, in some instances, the majority of 
a program may never use the 8087 and can still be used on systems which do not 
have an 8087 so long as these opcodes are avoided. For these programs, the -8087 
option allows the USES__8087 flag in the load file to be turned off. It is the user’s 
responsibility to assure that these opcodes are never used on machines which do 
not have an 8087, as the hardware will hang forever! 
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See Also: 

DUMP 

SPATCH 
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P ATH - Change command search path 

Syntax: 

path searchpath 

• This is a local shell command • 

Description: 

Each time a command which does not start with a slash is executed by the shell, a 
list of directories is searched for an executable file. The default is 7cmds/ M 
followed by the current directory. This may be changed using the PATH 
command followed by a list of directories surrounded by exclamation marks. For 
example, to search the current directory followed by "/cmds" followed bv 

i U£)vi/ WiliUo 

path ! !/cmds/!/user/cmds/! 
and to return to the default 
path !/cmds/n OR path 
You may print your current search path with 
path ? 
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Syntax: 

poll [-{-verbose] [-verbose] [\-logJile] 

[p -polljperiod ] [r -retries] [s=slow poll_period ] 


poll & 
poll +v 

poll l=poll.log 
poll p=20 & 


Run the poller. 

Run poller with full screen display. 
Create a log of status changes. 

Poll nodes every 20 ticks (1 second). 



The POLLER is responsible for ensuring that resources are reclaimed when a node 
goes down. It should be run on a node which is always UP, probably the node 
which is used to download other nodes, or acts as a fileserver to other nodes. 

The POLLER scans all nodes which are alive and ensures that they are capable of 
receiving communications. If a node fails to respond to the poller in a reasonable 
amount of time, it is marked as DOWN and all other nodes are informed. This has 
the effect of releasing any resources which this node may have been used 
anywhere on the network. 

The POLLER will also poll one DOWN node for every complete cycle of polling 
UP nodes. This is called the slow poll and may be eliminated by specifying M s=0". 
The slow poll will discover nodes which have recently booted, but at a much 
slower rate than it finds nodes which have crashed. The s= option can also be used 
to reduce the rate of slow polls if discovering newly booted nodes is not critical. 

The POLLER will poll a node every 5 ticks which amounts to 4 polls per second. 
The p= option can be used to alter this rate, but the default rate provides good 
results for most network configurations. The POLLER decides that a node has 
crashed when it has attempted to poll the same node 3 times without receiving a 
response. The number of retries can be changed with the r= option, but 3 retries 
should be sufficient since QNX will always reply to poll messages immediately if 
it is UP, and the network should never be so busy that a poll message can’t be sent 
and a reply received within 1 second. 
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The operating system will not initiate any communications with another node 
unless it thinks that node is UP. 

When a node changes from UP to DOWN, the operating system automatically 
releases any resources which were being used by tasks on that node (usually files), 
and unblocks any local tasks which were waiting for messages from tasks on that 
node. This cleanup does not take place on the transition from UP to BUSY, or 
BUSY to DOWN. 

BUSY status is useful to temporarily remove a node from the network without 
releasing any resources on other nodes. This might be done on a node before using 
the debugger to prevent the POLLER from flagging the node as down. 

alive +b 

When the debugging session has ended, the alive command can again be issued to 
tell the poller that the node is now UP and ready to receive communications from 
other nodes. 

alive -Hip 

When a node is first booted, it is usually a good idea to inform the poller that the 
node is now up rather than waiting for die slow poll to discover the fact. The poller 
will then broadcast this information to all other nodes in the network. To achieve 
this, include the ALIVE command in the "/config/sys.init" file. 

alive +n 

NOTE: For proper operation, only ONE poller should be running on a QNX 
Network. 

See Also: 

ALIVE CLRHOUSE KILL_VCS NACC 
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PMI - Set priority 

Syntax: 


pri number 
pri -{■number 

pri -number 


• This is a local shell command • 

Description: 

Set the priority of commands executed by the shell. A V increases it while a 
decreases it. If no argument is given the priority is set to the default of eight. The 
priority must lie within 4 and 15 with 4 being the highest priority. Smaller values 
have higher priority. The command. 

pri -1 

will ADD one to your priority number which will cause the command to run at 
LOWER priority. The priority number may be seen by using the tsk command and 
noting it’s priority. This command does not affect the priority of the shell itself, 
only die commands executed by the shell. 


[PRI] 
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PROMPT? 


PROMPTT - Display tty number 

Syntax: 

promptt 

• This is a local shell command • 

Description: 

The PROMPTT command will toggle the display of your tty number before the 
standard shell prompt. It is useful when you have several windows mounted on the 
console which may be difficult to tell apart. 

3 $ will be displayed if you are logged into $tty3 


Utilities 


[PROMPTT] 



none 


PRTSC saves the console screen, then pops-up a menu in a full screen window 
which allows you to select one of several options. One of these choices allows you 
to make a hardcopy of the saved screen. Another allows you to save the screen 
contents in a file. 

This command is invoked automatically by QNX whenever the user types 
Ctrl-Alt-PrtSc on the console keyboard. The screen is restored automatically when 
PRTSC terminates. PRTSC can therefore be used as a means of executing 
commands without destroying the contents of the screen. 

A file of additional menu items can be created by the user, which will be added to 
the menu already supported by PRTSC. This file is called /config/prtsc.cfg and 
consists of one or more text lines. The first 12 characters are used as the menu 
identifier. The command which starts in the 14th column will be executed when 
this menu item is selected. A sample file would look like: 


Calculator 

Mail 

Cardfile 

JkP 

Chat 


calc +f 

mail 

cardfile 

ap 

chat 


[PRTSC] 
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PETSC 


With the above data in the file /config/prtsc.cfg, PRTSC would display a menu 
like: 


a) Do Nothing 

b) Print Screen 

c) Save Screen 

d) Calculator 

e) Mail 

f) Cardfile 

g) AP 

h) Chat 


Typing the indicated letter will perform the associated function. Also, an inverse 
"idee cursor can bo moved with the UP and DOWN arrow keys. Typing Enter will 
select the highlighted function. 

See Also: 

CALC 
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PWD 

PWD - Print Working Directory 



The PWD command will display the complete pathname of the current directory. 
Under the network version of QNX, the pathname will be preceded by your node 
number in square brackets. 

See Also: 

CD 

LS 


[PWD] 
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qcp [device] SEnd [options]* srcJile[,dst Jile] [x-indexJile] ^ 
qcp [device] SJSceive [options]* [^forcedfilename I p—prefix] 



device 

-make„dir 

+newest 

+relaxed_timing 

+today’s_date 

-s-verbose 

-verbose 

filename 

p-prefix 

s=packet_size 



Name of QNX device to use (default: current device). 
Suppress making directories for received files. 
Receive only files that are newer than existing files. 
Double timeouts and quadruple retry counts. 

Place today’s date on received files. 

Display error status while transferring files. 

Display nothing during the transfer. 

Force received files to have this name. 

Place this prefix on the names of any received files. 
Set size of transmitted data bursts (default: 2048). 


QCP provides the error checked file transfer protocol needed by Qtalk, Qterm or 
QCL ( QNX Communications Language) to transmit or receive files. The QCP 
protocol achieves both high efficiency on packet switched networks and high 
reliability due to the use of 16 bit CRCs (Cyclic Redundancy Check). QCP is 
specific to the QNX environment and automatically sends files with their path 
name, attribute, permissions and date fields intact. 

QCP is another one of those commands that needs the timer administrator task 
running in the background. This can be accomplished by executing the command: 

timer & 


or by placing it in the sys.init file so that it is always present. 

When connected to another QNX system through a serial port and running Qtalk or 
Qterm, files can be transferred from the remote system to the local system by 
giving the remote system a command of the form: 
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qcp se filel file2,file3 x=file4 

This example would send filel, send file2 and cause it to be received with the 
filename "file3” and then send all the files named in the index file n file4". Index 
files are easily created with the LS or FILES command. The Qtalk and Qterm 
programs will automatically start QCP on the local side to receive the file. To 
explicitly invoke QCP to receive a file, a command of the form: 

qcp $mdm re 

should be given. This would start up the QCP task such that it would receive the 
file from the $mdm device. 

To send files to the remote system, Qtalk or Qterm can be commanded to invoke 
QCP with the appropriate options to send the file. Before starting the QCP send, 
the remote side must have a QCP task in a receive state. This can be accomplished 
by giving the remote system the command: 

qcp re 

If the send side of the QCP file transfer is being explicitly started from another 
task, rather than automatically from within Qtalk or Qterm, the send command 
would look like: 

qcp $mdm se filename 

This would send the named file(s) through the $mdm device using the QCP 
protocol. 

While a QCP file transfer is in progress, it can be aborted by pressing the space bar 
or the escape key. QCP will provide a prompt to which a ’y’ can be supplied to 
abort QCP. If a remote QCP in a receive state must be shut down, the control 
character sequence A V A X A X will abort it. 

See Also: 

FILES LS QTALK 
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QTALK - Talk over Communications Line 

Syntax; 


qtalk [system] [options]* 

Options: 

system - The name of a system you wish QTALK to call. 

+echo - Local echo. 

+iflow - Support flow control on the incoming data. 

-parity - Ignore 8th bit of received characters. 

c-hh - Specify character which invokes QTALK commands. 

(Default is CTRL-A). 

d=delchar - Replace ASCII RUBOUT with delchar . 

1 =logfile - Log session into "logfile". 

m -modem - Name of async device (Default: $mdm). 

h-buf_size - Size of receive buffer. (Default: 4000). 

k=hh - Kick character. 

p-hh - Pause or turnaround character. 

o-option - Option(s) to be used for file transfer protocol. 

Examples: 

qtalk home - Phone home. (Pretend you are E.T.). 

qtalk +e d=08 - Communicate with a machine which does not echo (half 

duplex) and expects an ASCII BACKSPACE to delete 
characters. 

qtalk i=$lpt - Communicate with another system with hardcopy record, 
qtalk k=ll p=0d - Prepare to send a file to a mainframe which sends Ctl-Q 
when ready for input. 

qtalk m=[l]$tty6 - Use the $tty6 serial port on node-1. 
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QTALK allows QNX users to communicate with other computers via a modem. 
The destination may be another host computer (mainframe) in which case QTALK 
allows your computer to be used as a terminal. QTALK also allows two QNX 
users to communicate and transfer files. 

QTALK will send any characters typed on the keyboard to the other system over 
the modem. Any characters received by the modem are displayed. In local-echo 
mode, typed characters are echoed on the display as well as being sent over the 
modem. 

A recording of a QTALK session can be filed using the 1= option. 

l=$lpt 

or 

i=/tmp/logfi!e 


A special COMMAND character allows special modes and options to be set while 
within the QTALK environment. This special character defaults to control A 
(Ctrl-A), unless changed with the c= option before entering QTALK. The character 
following the COMMAND character is interpreted by QTALK to perform some 
special function. If the next key is not a valid QTALK command, then it will be 
echoed to the modem. Hence Ctrl-A Ctrl-A will send a single Ctrl-A to the 
modem. 

The QTALK commands can be one of the following: 

b - BREAK 

Send a break over the modem. Breaks may also be sent by pressing the 
BREAK key (Ctrl-BREAK on the console keyboard). NOTE: if you 
press the break key four times in a row, without typing any intervening 
characters, QTALK will terminate, as if you had invoked the x (exit) 
command. 

c - CHANGE DIRECTORY 

QTALK will prompt you for a new directory name, and will attempt to 
change directory to it. If successful, the specified directory will become 
die current "working directory" (see the command PWD), for the dura¬ 
tion of QTALK, or until you change directory again. When QTALK 
terminates, your current working directory will revert to the directory 
you were in when QTALK was invoked. 


[QTALK] 
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d - DIAL SYSTEM 

QTALK will prompt you to enter a system name. If that name is found 
in the dial.dir file, the associated string (usually a modem dialing 
command) will be sent to the modem. If you enter a question mark (?) 
for the system name, the contents of the dialing directory will be 
displayed, and you will re-prompted for the system name. Pressing 
return, without entering a system name will abort the dialing command, 
and return you to normal communications mode. 

Dialing is implemented by looking up the system name (which can also 
be specified on the command line when QTALK is invoked) in a file 
Iconfigl dial.dir. This file is of the form: 

system-name dialing-command 

The system name may be any string of characters (except for spaces and 
tabs) of any length. The dialing command is any characters (including 

spaces and tabs) which are sent to the modem. Typically this would be 
the dialing command for your modem, and the phone number to dial. 
The system name and the dialing command are separated by one or 
more spaces and/or tabs. An example dialing directory entry that 
instructs a Hayes-compatible modem to call the QUICS update system 
would be: 

quics ATD16135910934 

e - ECHO 

The local echo feature is toggled. Some mainframes expect the 
"terminal" to perform local echoing. 

h - HANGUP 

The CTS/RTS lines will be lowered for approximately 1/2 a second. 
This permits modems which support hardware hangup to do so. 

1 - LOG 

Begin or end logging of this session. If no log file is open, then QTALK 
will ask for the name of a file to log into. If logging is already in 
progress, then it will be terminated and the log file closed. LOG will 
record every character which is sent OR received in the log file. 

o - TRANSFER OPTIONS 

QTALK prompts for the options to use when invoking a file transfer 
protocol. Often, the QCP "+newer” option is used to condition the 
transfer to ignore files which are older than the copy you already have 
on disk. This can be a real time-saver when downloading an update 
from QUICS (the QNX Software Update system). 
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For example: 

Transfer options: +n 
p - PARITY 

Ignore parity (top bit) of received characters. If this option is already 
set, then turn it off. 

q - QUIT and HANGUP 

This does a hangup command (see above) before exiting from QTALK. 
s - SEND A FILE 

Send a file using the QCP file transfer protocol. This sends a file to 
another system running the same protocol, which is far more secure 
than simply writing the file to the modem. 

QCP is a very secure, fast protocol specifically designed for QNX. It 
permits information about the file (the file date, attributes and 
permissions) to be transferred, as well as the file contents. QCP is 
ideally suited for use over public packet switch (X.25) networks, as well 
as direct modem-to-modem connections. If communication errors are 
encountered, portions of the file will automatically be resent until the 
far end acknowledges correct reception of the file. 

More than one file can be sent by specifying x=filename when QTALK 
asks for the file to send. This file will contain a list of files to send, one 
per line. You can also specify more than one filename, separated by 
spaces. 

QTALK allows you to follow the name of the file to send with the name 
of the destination file separated by a comma. This is also true for file 
names within an index files (x=). For example: 

Send file(s)? filel mam.c,new_main.c 

will send the file "filer* as "filel" and the file "main.c" with the name 
"new_main.c". If no new name is given, then QTALK will create a file 
with the same name as the file which is sent. 

Files received by QTALK using the QCP protocol will have the same 
attributes and date as the file on the sending machine. 

Protocol transfers require that the modem port be configured for 8 bit 
data (see the STTY command). 


[QTALK] 
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u - UPLOAD TEXT 

Upload text to another system. This permits text files to be sent to 
another computer using a simple handshaking protocol based on the 
pause and kick characters, specified on the command line. If local-echo 
is not enabled (see the e command, above), QTALK will wait for the 
character to be echoed by the remote system, before sending the next 
character. If local-echo is enabled, the text will be written to the 
modem with pauses only when the pause character is encountered. 

A text upload may be aborted at any time by pressing the Escape key 
(ESC), or by pressing BREAK (Ctrl-BREAK on the console keyboard). 

NOTE: you must specify both the pause and kick characters to use the 
upload handshaking protocol. If either (or both) characters are not 
defined, then it is the same as issuing a w (write) command (see below). 

w - WRITE 

Write a file to the modem. The file will be transmitted over the modem, 
and also echoed on the display if local echo is enabled. WRITE also 
allows files to be transferred to mainframes or other users with 
handshaking, but no error checking (described below). 

Writing to the modem may be aborted at any time by pressing the 
Escape key (ESC), or by pressing BREAK (Ctrl-BREAK on the console 
keyboard). 

The primary difference between upload and write is whether or not to 
wait for the character to be echoed by the remote system, before sending 
the next character. 

x - EXIT 

Exit from QTALK without performing a hangup. It is probably a good 
idea to get in the habit of using the q (quit and hangup) command for 
leaving QTALK, unless you really mean to not perform a hangup. 

! - Execute a shell command 

This permits you to execute any command from within QTALK. 

Typical usage of this would be to execute the Is command to discover 
what files are in your current directory prior to uploading or sending 
some of them, or to execute non-native file transfer protocols (such as 
Xmodem or Kermit) from within QTALK. 

When communicating at high baud rates, the logging facilities may interfere with 
apparent response. The QNX operating system internally buffers up to 256 
characters while data is being written to a file or printer. QTALK adds another 
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level of input buffering which can hold a larger number of characters. This buffer 

size can be changed with the b= option on the command line. The default buffer 
size is 4000 characters. Very high speed modems, or logging on slow printers or 
floppy disks may cause this buffer to be overrun, in which case some characters 
may be lost. Input flow control can be enabled (see STTY) prior to invoking 
QTALK, or at the time QTALK is invoked using the "+i" option, to prevent 
characters from being lost in these cases, provided that the machine which is 
sending the data supports flow control of its output. 

Two methods are supported by the QTALK utility which allow users to transfer 
files. The simplest method is invoked using the upload, write and log commands 
to send and receive text files to/from another system. No error checking is 
performed so this method should only be used when communication lines are good 
(ie. direct connect lines or local modem connections). The send and receive 
commands use a more sophisticated protocol which includes error checking and 
re-transmission when transferring files to other systems. 

Two parameters can be specified on the command line to select the protocol which 
is used by the upload command. These parameters are: 

p =hh - PAUSE or turnaround character (hex). If upload detects this 

character in the file it is sending, it will be sent and QTALK will 
pause waiting for a KICK character to be received. Setting PAUSE to 
a CR (0D hex) will cause upload to send one line at a time, 
k =hh - KICK character (hex). This character is used in conjunction with the 
PAUSE character by upload to handshake with other computers 
when transferring files. 

These parameters allow the protocol to be adjusted according to the characteristics 
of the hardware at each end. 

The write command can be used to transfer files to other systems which can accept 
input without needing to pause for any form of handshaking. For slower systems 
(especially systems running full-duplex), the upload command is more 
appropriate. The log command can be used to take "snapshots" of data from a host 
mainframe at slow speed. 

To send a file to a mainframe, the user can use QTALK to enter into input mode of 
the mainframe’s editor. The upload or write command can then be used to send a 
QNX file to the mainframe. QTALK should be invoked with p=0d to cause one 
line at a time to be sent. KICK should be the prompt character which is printed by 
the mainframe editor whenever it is ready to receive a new line. On some 
mainframes this may be a Ctl-Q or it may be a prompt character such as a dot (.). 


[QTALK] 
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The d= option is very useful when communicating with mainframes which have a 
different RUBOUT character than you are used to. Many mainframes use the 
backspace key (hex 08) to erase a character. QNX systems default to the ASCII 
RUBOUT character (hex 7F). Typing: 

qtalk d=08 

will cause QTALK to translate your RUBOUT key into backspace automatically. 

See Also: 

CHATTR 

QCP 

STTY 
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QUERY - Query the utilization of a disk 

Syntax: 

query [[node]drive] [-address] [+display] [+hex] [+visual] 

Options: 

-address - Don’t print addresses at the side of the bitmap 
displayed with the +display option. 

+display - Display bitmap using character graphics and decimal addresses. 
4-hex - Use hexadecimal notation for the 4-display option. 

4-visual - Maintain a real time bitmap display. 

Examples: 

query 

query 3 
query 3 4-d 
query [2]1 4-v 

Description: 

QUERY allows the user to determine how much room is free on a disk. QUERY 
will examine the bitmap of the disk on the indicated drive and report how many 
blocks are used and what percentage of the total available blocks this corresponds 
to. 

The 4-visual option is useful for monitoring how much space is left on a ramdisk or 
floppy disk while files are being copied to it. If the bitmap is too large to display 
on a single screen, the visual update is terminated. To exit from the continuous 
display mode, press any key. 

See Also: 

CHKFSYS 


[QUERY] 
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QUEUE - Implement queued message passing in QNX 

Syntax: 

queue Oglobal] [p=signal j>ort] & 

Options: 

+global - Globally register the queue manager. 

p^signal jport - Specify which port to use. If unspecified, the 
first free port will be used. 

Description: 

QUEUE implements queued message passing in QNX. It should only be started if 
needed by applications. Although no QNX Software Systems applications are 
using QUEUE (as of January, 1988), this may not always be true. A number of 3rd 
party application developers are using QUEUE. If you have any doubt as to 
whether or not you should run QUEUE, check the documentation for the applica¬ 
tions you wish to run, or contact the vendor or QNX Software Systems technical 
support. 

If you ever need to terminate QUEUE, use the SLAY command: 
slay queue 

See Also: 

Queue management routines in the QNX C compiler manual 
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RM - Remove files 

Syntax: 

rm file* [+interactive] [+recursive] 

Options: 

+interactive - Display each file and ask whether 
to remove. 

-{-recursive - If a passed file is a directory 

the entire contents of the directory 
(including subdirectories) will be 
removed. 

Examples: 

rm *.o 

rm dirl dir2 +r 


rm * +i 
rm "test" 


Description: 

RM removes one or more files from a directory. Removal of a file requires write 
permission on the file itself. 

If a designated file is a directory, an error is printed unless the -{-recursive option is 
specified. In that case, RM recursively deletes the contents of the specified 
directory and then the directory itself. Note that RM invokes the WS command for 
recursive removal. Placing the RM command in ramdisk can speed this process. 

The -{-interactive option will cause RM to print the name of each file it is about to 

remove. A single character response of the letter ’y’ (for yes) will remove the file. 
Any other response will leave the file untouched. This option may be combined 
with the -t-recursive option. 


- Remove all object files. 

: +I • 

- Remove dirl and dir2. If they are 
directories remove all files and 
directories under them. 

Query for each file. 

- Query whether to remove each 
file in the current directory. 

- Remove all files containing the 
word ’test’ in their name. 


[RM] 
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RM is a more advanced version of the command FREL. 

See Also: 

DREL FREL 
RMDIR WS 
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RMDIR - Remove directories 

Syntax: 

rmdir directory * [+interactive] 

Options: 

+interactive - Display each directory and ask 

whether to remove. 

Examples: 

rmdir test 

rmdir test 3:/tmp 

Description: 

RMDIR will remove a directory from the disk. Only empty directories can be 
released. If the RMDIR command verifies that the directory is empty, then the 
space used by the directory will be reclaimed. 

If a directory is to be removed which is at the top level (root), it is usually 
necessary to specify the correct drive prefix as in the last example. 

The +interactive option will cause RMDIR to print the name of each directory it is 
about to remove. A single character response of the letter ’y* (for yes) will remove 
the directory. Any other response will leave the directory untouched. 

See Also; 

DREL 

FREL 

RM 
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Syntax: 


rtc type [4-set] [+localtime] 

Options: 

type - Type of clock/calendar card. 

+set - Set date/time of card. 

4-localtime - Use localtime. The default is GMT time. 



rtc at - Get QNX date from AT clock, 

rtc at 4-set - Set AT clock with QNX date. 

Fi€ • “ display supporieci caros. 



This command will set the QNX date and time from a battery backed-up 
clock/calendar card. 

PLEASE NOTE: The types of cards supported by this program were verified at 
the time they were created. We do not warrant in any manner that they will 
necessarily work on newer versions of these cards or cards similar in design. 

This command should be included in your "/config/sys.init" file if you have one of 
these clock/calendar cards, or if your machine has a built-in clock/calendar (such 
as the IBM AT): 

rtc at 

If the time in your clock/calendar card is incorrect (perhaps the battery has been 
replaced), it can be set using the +set option of RTC. First, set the QNX time with 
the DATE command, then issue the RTC command: 

date 10 Mar 86 12 38 pm 
rtc ast 4-set 


[RTC] 
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The RTC command supports many different types of clock/calendar cards. To find 
out which cards are supported by your version of RTC, type: 


rtc ? 

In some cases a hardware vendor has sold many versions of the same card, such as 
the Quadram and AST cards. The RTC command will identify the versions with a 
number after the name. In general, the smaller the number, the older the card. 

quadl Oldest style quad card 

quad2 More recent quad card 

and so on... 


CLOCK 

DATE 
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SAC - Display system activity at each priority level 

Syntax: 

sac [-repeat] [+scale] [+vertical] [r=sec] [i=inertia] 

Options: 

-repeat - Suppress continuious update of display. 

+scale - Seale largest bar to screen size. 

+verticle - Run bars verticaly (this is slower). 

r-sec - Repeat rate (screen update period). Default 1.. 

i =inertia - Sensitivity to changes. Defaults. 

Examples: 

mount lib /config/sac.slib Shared lib must be mounted. 
sac 

sac i=8 

Description: 

SAC will display a bar graph showing the amount of processor activity at each 
priority level. In an idle system you should see one large bar at priority 15. The 
sum of all the bars should add up to 100% unless the -scale option is specified. 

This option expands the largest bar to fill the screen, scaling all other bars resulting 
in a finer resolution. 

Unless you request the -repeat option, SAC will continuiously update the screen at 
the requested poll period. SAC itself will cause some processor activity. This 
activity will be greater if the +verticle option is selected. On the console, your 
TCAP entry should be set to qnx to minimize SAC’s cpu useage. In general, your 
console should always be type qnx. 

tcap set qnx 


To use SAC you must mount a shared library which collects statistics on processor 

activity at each priortity level. This shared library integrates these numbers over 
time. What is displayed is the average over the integration time. Smaller values of 
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inertia average over shorter periods resulting in a faster response to changes in 
system activity. Larger values allow you to monitor average activity over a longer 
period of time. The averaging periods are as follows: 


i= 

Time 


i= 

Time 


5 

1*5 

sec 

11 

102 

sec 

6 

3 

sec 

12 

3 

min 

7 

6 

sec 

13 

6 

min 

8 

13 

sec 

14 

13 

min 

9 

25 

sec 

15 

27 

min 

10 

51 

sec 





The value of i must lie between S and 15 inclusive* 


See Also: 


[SAC] 
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SEARCH - Define or Query the Disk Search Order 


Syntax: 

search drive* [+remote] 

Options: 

^remote - Define search order for requests from 
other nodes on the network. 

Examples: 

search - Query the current disk search order 

search 5 3 

- Define the disk search order such that drive 5 is searched 
first, followed by drive 3. 

search 3 +r - Set remote search order to be drive 3. 
search 3 [5] 

- Search drive 3 then use node 5’s remote search order. 

Description: 

SEARCH defines the "order” in which die operating system scans disk drives 

while opening files. 

A default disk search order is setup at boot time by the operating system. If you 
boot from floppy diskette the disk search order is linear over your floppy drives. 

search 1 
’ or 

search 12 

if you booted from hard disk your search order will be disk 3 which is mapped to 
the the disk partition you booted from. Please read the section on hard disk 
booting for more details. 

search 3 
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If you boot over the network your search order will the remote node you booted 
from. 

search [nodeJbootedJrom_] 

It is usually desirable to change the search order to include mounted ramdisks and 
hard disks. Most users do not search the floppy drives at all. 

Adding new drives to the system with the MOUNT command will not 
automatically include the drive into the system search order. SEARCH must be 
used before these drives will be automatically scanned when loo king for files. Files 
can still be accessed on drives which are not included in the search order by 
preceding the filename with a drive prefix. 

If a number in square brackets is included, then the remote search order on that 
node is used. 

Requests for files on a local hard disk can come from two sources. They can 
originate locally from tasks on the same machine or remotely from tasks on other 
machines. The +remote option determines the search order which will be used for 
remote requests. A local ramdisk is usually excluded from the remote search 
order. 

See Also: 

MOUNT 

NACC 

PATH 
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SH - Execute Shell Commands 

Syntax: 

sh [options]* filename [ arguments ]* 

Options: 

4- back - Suppress the display of background task ids. 

4-menu - Internal use only. 

4-qdb - Internal use only. 

4 -initial - Execute the next argument as a command using 
the EC command, then accept input from the 
keyboard. 

4 -restrict - Restrict the commands and command line syntax allowed. 

The commands cd, path and the characters >, / and A 

become invalid. 

4 -string - Execute the next argument as a command then terminate. 
4 -transform - Cause the shell to transform itself into 
the first command it executes. 

4 -verbose - Print each command line before executing. 

Examples: 

sh commands 

sh /cmds/mycc test.o c=test l=/lib 

Description: 

SH is the command interpreter (referred to as the "shell") and acts as the interface 
between the user and QNX. SH can take commands interactively from the 
keyboard or from a batch file. The following documentation concerns itself mainly 
with batch file operation. Interactive operation is described in a chapter in the 
QNX manual. This chapter also contains background information on the shell 
which is recommended reading. 

SH allows the user to execute the commands found in a file as if they were typed 
on the keyboard by the user. Each line in the file will be executed as a command 
by the shell. The shell’s arguments can be included into these commands by 
referencing them as #1 #2 ... #9. Any instance of #1 will be replaced by the 1st. 
argument on the command line. For example, in the second example above, #1 is 
replaced with "test.o”, #2 will be replaced with "c=test" and #3 will be replaced 
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with "l=/lib" before the commands are executed. #4 through #9 in this example 

will be replaced with the null string. The complete list of # macros are as follows: 


## 

- number of arguments 

#% 

- task number of shell 


- task id of shell 

ft 

- exit status of last command 

m 

- task id of last background task 

#c 

- cyclic number which changes each second 

#g 

- group number of user 

#k 

- accept a line from the keyboard 

#m 

- member number of user 

#n 

- node number 

#p 

- cpu type 

#t 

- tty number 

#u 

- userid of user 

#v 

- qnx version number 

m 

- name of shell command 

#1 to #9 

- arguments passed to shell command 

#* 

- all arguments #1... #nn 


The #p macro contents is defined as follows : 


PC 1 

AT real mode 2 

PS2 4 

old HP Vectra 5 

PS2 model 30 6 

AT Protected mode 42h 

PS2 protected mode 44h 


old HP Vectra Protected mode 45h 

SH allows a user to define his own commands. Commonly repeated sequences of 
commands can be grouped into one command file thereby allowing the user to 
execute this group of commands with a single command. 

An example of a command file would be a file called "rename" which contains the 
following line: 

chattr #1 n=#2 

The user would then type 

sh rename bill joe 
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to change the name of file ’’bill" to "joe". If the command is used quite often, the 

user can remove the need for typing "sh" every time by giving the command file 
execute permission with the CHATTR command (use: "chattr rename a=+e"). 

The user can now type: 

rename bill joe 

Each command will return a value when it terminates. This value will usually be 
zero if the command terminates normally. 

The +i option is used by the LOGIN command to pass the initial command to 
execute which was read from the password file. 

If you type a Ctrl-d to the shell it will terminate. This is useful when invoking the 
shell from within the editor (or any command) by typing a Ctrl-z. Typing a Ctrl-d 
will return you to your application. 

The complete list of shell batch commands follows: 

back - suppress background lid 

When you run a program in background using the & symbol the shell will 
normally display the taskid of the background task created. In shell files this may 
not be desirable. The BACK command suppresses this display. 

base number - base for number expansions 

When an integer shell variable is displayed it will be displayed as either a 4 digit 
hexadecimal number or a 5 digit unsigned number. The argument for base should 
be either 10 or 16. 

break task_id - break a task 

The indicated task will be killed by setting a break exception on it. You may 
obtain the tasks identity with the TSK command. 

cd [directory] - change directory 

Since each task has its own directory this command must be handled by the shell. 
Placing it in a command which loaded off the disk would change the directoiy of 
the new task loaded but NOT the directory of the shell. This should be kept in 
mind when escaping from a command via Ctrl-z. You can NOT change your 
directory then return back with the new directory in effect. This is documented in 
detail in the utilities section of your binder. 

debug [text] - debug a command 

If text is missing then the debugger is invoked with the data and code segments 
pointing to 4K of free memory. If text is present then the debugger is invoked after 
loading the command indicated. 
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debug Is 

The debugger must be mounted or the request for debug is ignored. Please read 
the debugger documentation first! If you don’t, simply type ’g’ followed by a 
carriage return to return from the debugger. 

defpipe path ~ pipe temp files 

The DEFPIPE command allows you to change the pathname where temporary pipe 
files are placed. 

defpipe my__pipe 

The default is 

defpipe /tmpL#n#$ 


ec shellJile - execute sh file 

The EC command causes the shell to temporarily take its input from the indicated 
file. Since the execution of commands in the file is performed by the current shell, 
it is possible to execute commands like CD, PATH, PRI, PROMPTT etc..., which 
affect the environment of the shell which executes them. 

This is especially useful in the password file where you will often see a line such 
as 


ec userinit 

EC commands cannot be nested, 

else - conditional 

The ELSE command precedes a group of one or more commands terminated by an 
ENDIF which are to be executed if the preceding IF condition was false. An ELSE 
must be within the scope of a preceding block IF command. For example 

if +f #l.c then 

cc #1 m=map 

sort map f=l,3 +r 
else 

type File #Lc does not exist 
endif 


endif - end a block if 

The ENDIF statement ends a list of statements following a block IF or an ELSE. 
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exit [number] - exit shell with status 

The EXIT command will exit the shell and return back either the indicated status 
or the status of the last executed command if status is omitted. The status argu¬ 
ment is assumed to be in the current base set by the BASE command. 

goto label - transfer control 

The GOTO command transfers control to the line following the one containing the 
indicated label. A label is entered as a colon (:) followed by label name of up to 8 
characters. For example 

:loop 

type This is a loop 
goto loop 

If the label does not exist then the shell file will terminate. 


if test cmd - conditional 

The IF command allows conditional execution of QNX commands. There are two 
forms of this command. If the argument command is the keyword THEN, then 
commands on the following lines until an ENDIF are considered to be within the 
scope of the IF. This is called a block IF. Otherwise, only the indicated command 
is conditionally executed. There can be no ELSE or ENDIF. If the TEST is true 
then the command is executed. 


if +f pathname 

command 

if +d pathname 

command 

if +m pathname 

command 

if +a nodeid 
if eq argl argl 
if ne argl argl 
if It argl arg2 
if ge argl arg2 

command 

command 

command 

command 

command 


true if pathname is a file 
and exists 

true if pathname is a directory 
and exists 

true if pathname has the modified 
bit set 

true if node is alive 

true if argl is identical to arg2 

true if argl is different from argl 

true if argl is less than argl 

true if argl is greater than or equal 

to argl 


The arguments in the last two forms may NOT contain an embedded blank unless 
the argument is enclosed in double quotes. 

if eq "#1" "Clarke Kent" frel 

You may match a null (or missing) argument using the following trick, 
if eq abc #labc type Argument missing 
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As a final warning, remember that the # shell variables which result in a number 
are always expanded to 4 places if hexadecimal and 5 places if decimal. 

if eq #& 0000 exit 

It is possible to nest block IFs. • 

if eq #1 abc then 
if eq #2 def then 
type abc def 
else 

type abc NOT def 
endif 

else 

if eq #2 def then 
type NOT abc def 
else 

, type NOT abc NOT def 
endif 
endif 


kill taskjd o.. - kill a task 

The indicated tasks will be killed. You may obtain the tasks identity with the 
TASK command. This is included in the shell to allow you to kill a task even 
when there are no free task descriptors in the system to create a new task. The 
escape sequence #& refers to the last background task you created. 

kill #& 

If the first argument starts with a plus sign (+) it is taken as a system exception to 

set on the remaining taskid’s specified. For example 

kill +0001 050c -set exception hangup on task 050c 

Refer the to chapter on MULTI-TASKING for more information on exceptions. 

You may wish to refer to the SLAY command to remove a task by if s name 
rather than if s task id. 


entty tty cmd - create task on another tty 

The ONTTY command executes the indicated command on the indicated tty. The 
command is detached from your terminal and inherits your accounting information 
and current directory. After mounting a console you may wish to create a SHELL 
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or LOGIN on that console. 

mount console $con2 
ontty $con2 sh 
OR 

ontty $con2 login 

If this command is combined with the syntax of remote task creation, then the 
remote node should precede the ONTTY. You may also specify the node number 

as part of die device name. 

[4] ontty $con2 ed file 
ontty [4]$con2 ed file 

These will create the editor on $con2 of node 4. The editor will attempt to read the 
indicated file using the search order on node 4. 

passon - password protection 

The PASSON command will cause the LOGIN command to look for the file 
"/config/pass" and enforce password protection on login. If this file does not exist 
you will be unable to login. 

Once passwords are enabled, they cannot be turned off. 

path searchpath - change search path 

Each time a command which does not start with a slash is executed by the shell a 
list of directories is searched for an executable file. The default is "/cmds/" 
followed by the current directory. This may be changed using the PATH 
command followed by a list of directories surrounded by exclamation marks. For 
example, to search the current directory followed by "/cmds" followed by 
"/user/cmds" 

path ! !/cmds/!/user/cmds/! 
and to return to the default 

path l/cmis/l! OR path 

You may print your current search path with 

path ? 


pause - pause for carriage return 

The PAUSE command will pause and wait for you to type a carriage return. When 
used with the TYPE command it gives you the opportunity to change disks or 
perform some other action before executing the next command. 


[SH] 


Utilities 



SH 


pri [+1 -^number - set priority . . , , 

Set the priority of commands executed by the shell. A ’+’ increases it while a - 

decreases it. If no argument is given the priority is set to the default of eight. The 
priority must lie within 4 and 15 with 4 being the highest priority. Smaller values 
have higher priority. The command. 

pri -1 

will ADD one to your priority number which will cause the command to ran at 
LOWER priority. The priority number may be seen by using the task command 

and noting it’s priority. This command does not affect the priority of the shell 
itself, only the commands executed by the shell. 

prompt! - display tty number 

The PROMPT command will toggle the display of your tty number before the 

standard shell prompt. It is useful when you have several windows mounted on the 
console which may be difficult to tell apart. 

3 $ will foe displayed If you are logged into $tty3 


setvar op var val - set variable 

The user variable is set to a new value based upon the op type. 

String Variables 
setvar = s« value 

- assign string 

setvar | s« value 

- concatenate string 

setvar = oranges 
setvar | ”, apples” 


Integer Variables 
setvar = L number 

- assign number 

setvar + L number 

- add by number 

setvar - L number 

-subtract by number 

setvar x L number 

- multiply by number 

setvar / L number 

- divide by number 

setvar % L number 

»modulus by number 

setvar = 10 123 

- set 10 to 123 using current base 

setvar = 10 0tl23 

- set iO to 123 using base 10 

setvar = iO 0x123 

- set 10 to 123 using base 16 

setvar + il #i0 

- add iO to 11 updating il 

setvar = sO a#k 

- get line from keyboard, the Vis 


to ensure some data is assigned in 
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case a blank line is entered. 


sharoff - don 9 t share code segments 

This option will stop the sharing of code. See SHARON for details. 

sharon - share code segments 

This option will cause the task admin to scan the code table and check if a task is 

already loaded into memory. If so, it will link to the existing code and only load 
the data from the file. Note that this code sharing only occurs for commands under 

Vcmds 5 or those specified with a leading 7 s . This the default when the system 

boots. 

shift - shift # args down one 

The SHIFT command allows shell commands access to arguments beyond #9. 

Each argument is shifted one position to the left. #0 becomes #1, #1 becomes #2, 
... and #9 becomes what would have teen #10. The following shell command will 

print any number of arguments passed to it. 

:loop 

if eq ## 0000 exit 0 

cype #i 

shift 

goto loop 

stype [text]* - type arguments 

Identical to TYPE, however, no carriage/linefeed is printed. 

sysup - set system up flag 

The SYSUP command will set die system up flag. Until this flag is set, Ctrl-z and 

Breaks will be ignored on terminals, preventing anyone from logging in, or 
terminating execution of the sys.init file. This flag is automatically set after the 
7config/sys.init’ file has run to completion. In some cases a user may wish to 
invoke a command in the ’sys.init’ file (like a menu shell) which prevents it from 
finishing. In this case you may force the system up placing the SYSUP command 
in your ’sys.init’ file before this command is invoked. 

then - conditional 

The THEN command can only be used on a line containing an IF command. It 
signals the start of a block IF. 

trap [label] - trap keyboard breaks 

The TRAP command allows a shell file to trap keyboard breaks. After executing 

each statement the shell checks to see if a keyboard break has been typed. If so, 

execution is transferred to the indicated label as though a GOTO statement had 
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been executed. If the label argument is missing then the break is ignored. If the 
indicated label does not exist then the shell command will terminate. 

trap - ignore keyboard breaks 

trap + » since label + will never occur 

this will cause the shell command 
to terminate on a break 

trap loop - transfer control to the label doop 

The following will print out a message until a break is typed. 


trap stop 
:loop 

type Type break to stop me 

goto loop 

:stop 

type Ok, you stopped me! 


type [text\* - type arguments 

The arguments following the command are displayed on the terminal, followed by 

a carriage return. This is often used within command files for informational 
purposes. 

verbose - toggle verbose mode 

The VERBOSE command toggles verbose mode of the shell. In verbose mode the 
shell will echo each line it reads to your screen before it executes it. 

zeros on/off - toggle verbose mode 

The ZEROS command turns on or off the printing of leading zeros when 
expanding numbers from shell variables. By default they are on to allow correct 
string comparisons in the IF command. They are usually turned off to generate 

text or pathnames which is more readable. For example. 

base 10 
zeros off 

type "You are on tty #t H 

See Also: 

LOGIN 
LOGOFF 
QNX Manual 
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SHARON/SHAROFF - Do/don’t share code segments 

Syntax: 


sharon 

sharoff 


* This is a local shell command • 


Description: 

When SHARON has been enabled, the task admin will scan the code table to check 
if a task is already loaded into memory. If so, it will link to the existing code and 
only load the data from the file. Note that this code sharing only occurs for 
commands under Vcmds’ or those specified with a leading 7’. This is the default 

when the system boots. SHARObr disables code sharing. 
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SIZE - Display the size of a file 

Syntax: 


size [file I x=file]* 

Options: 

file - Name of a file to size 

x-file - Index file containing a list of files to size 



size teste 

size inventory mailing list x=misc_files 

Description: 

SIZE will calculate the total number of characters in each of the given files. 

If more than one filename is given, then SIZE will also report the total number of 
characters and lines in all the files. 

The x= option allows a file containing a list of filenames to specify the files to 
count. This "index" file may be the result of redirecting the output of the FILES 
command (with -v option) or the LS command (with the +f option). 

See Also: 

FILES 

wc 
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SLAY - Kill a task by name 

Syntax: 

slay [taskjiame] [options]* 

Options: 

+break_only 
+dump 
+hold 

“hold 

+query_always 
“query 
+remote 
-son_kill 

+fid 

-verbose 
i=task_id 

n -nodejmm 
i~tty_num 
s=system_exc 
u~user_exc 
p =priority 

Examples: 

slay spooler n=2 - Kill spooler task on node 2. 

slay dragon t=3 -q - Kill dragon task on tty3 without querying first. 

slay test +d - Force memory dump on a test program. 

Description: 

SLAY is used to kill a task by name rather than by the task identification number 
(tid). This saves the user from having to first run the TSK utility before issuing a 
KILL command. Task names are specified without the path. An example would be 
a task called "/cmds/list" that the user wished to kill. Entering "list" as the task 
name would be sufficient to allow SLAY to find and kill it. 

There are many forms of this command. The simplest (and probably most often 
used) form of the command is of the form: 


- Set only a break exception on the named task. 

- Force task to perform a dump. 

- Hold the named task. 

- Unhold the named task. 

- Always query before killing a task. 

- Don’t query before killing tasks. 

- Also kill tasks started by remote nodes. 

- Don’t kill tasks which have son tasks running. 

~ Don’t kill the task return it’s task id to the shell. 

- Suppress messages about missing tasks. 

- Select task based on taskjd. 

- Search for named task on this node. 

- Limit task search to this tty. 

- System exception bits value (hex) 

- User exception bits value (hex) 

- Assign new priority to selected task(s) 
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slay ta$k_name 

This command will locate the task bearing the specified name and if only one is 
found both the KILL and BREAK exceptions will be set on it. If more than one 
task bears the specified name, the user will be prompted for a yes / no response for 
each task. When each task is listed in this form, the task name, tid, node number, 

tty and user group / member numbers will also be displayed to help the user make 
a selection. If no task name is specified, all tasks in the system will be matched and 
the user will be prompted for each of them. Answering die prompt with any 
character other than a *y* or ’n’ (with ’q\ for example ) will cause an exit from 
SLAY. 

By default, tasks that are running remotely from other nodes in a network will not 
be included in the scan for matching tasks. If these tasks must also be killed, use 
the +remote option. 

In more detail, the options supported by SLAY are: 


+break_only - Normally, SLAY will place both a break and a kill exception 
on the named task. This option will cause only the break 
exception to be set on the named task. 

+dump - This option sets a quit exception on the named task. If the 

dumper task has been installed a "snapshot" of the segments 
that make up the named task will be written to disk. QDB, 
the QNX Source level debugger, can then be used to browse 
through the execution environment at the moment of the 
dump. Please consult the QDB documentation for details on 
dumper. 

■fhold -hold - The hold option allows this utility to set or remove a hold 

status on the named task. One particularly useful example of 
this option is for a program which wishes to temporarily not 
have the CLOCK program display the time in the upper right 
comer of the screen. Issuing the command: 

slay clock +h 

would stop the time display. Once the application was 
finished, it could resume the time display with the command: 


slay clock -h 

+query - This option forces SLAY to query before killing the task. 

even if only one task is found with a matching name. This 
option is useful for viewing the other task information that 
SLAY will present before killing it. 
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-query 

+remote 

-son_kill 


+tid 


-verbose 

m-nodejmm 

i=tty_number 
s =system_exc 
m=user exc 


SLAY 

Force SLAY to not query if multiple occurrences of the same 
task name exist. This makes SLAY useful in shell 

commands if the environment is known to be appropriate for 
running SLAY in this manner. 

This option will allow killing local tasks that were started 
from another node. This option is needed to allow a user on 
his workstation to kill tasks that other network users have 
started on his node. 

This option will suppress killing tasks that have son tasks. A 
typical usage of this command would be within a shell 
command that shuts down shells on other tty devices. Setting 
this option would prevent SLAY from killing those shells if 
they had other tasks (such as editors ) running. Running 
SLAY with the 4-query option also set, will cause SLAY to 
prompt for a forced kill even if the named task has sons. 

This option will cause SLAY to return the task id of the first 
task which bears the requested name. If the named task does 
not exist, a task id of zero will be returned. This option then 
makes SLAY useful for shell scripts and C programs which 
wish to determine the task id of a task without having to 
resort to elaborate programming. Within a shell program, the 
usage would be: 

slay task_eame -ft -v 
type #? 

Within a C program, the SHELL library routine could be 
used to invoke SLAY to obtain the task id of a task as 
follows: 

tid = shell( "slay taskjiame +f -v" ); 

Suppress messages about a task not being found or having 
sons preventing the removal of the task. If the +query option 
is set, the prompts will not be suppressed. This option is 
useful within shell commands to suppress unwanted output. 
This option specifies the network node from which tasks 
are to be killed. This option allows convenient removal of 
tasks from a remote node without having to have a shell 
running on that node. 

This option specifies the tty from which tasks are to be 
killed. Tasks running from other ttys will not be affected. 

Set the specified SYSTEM exception bits on the selected 
tasks. See the ’/lib/exc.h’ file for exception bit definitions. 

Set the specified USER exception bits on the selected tasks. 
See the ’/lib/exc.h’ file for exception bit definitions. 
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p apriority - Change the priority of the the selected tasks to priority. 


Using the SLAY command, a very useful shell program can be created to allow a 
user at the console to position the first virtual console ($conO) to a particular 
directory, execute the shell command and cause all the other virtual consoles to 
also be positioned to the same directory. This is an ideal way to begin working 
within a particular directory. 

Sf This shell script removes shells from other consoles and starts up shells in 
the same directory as the current shelL This command can only be run from 
" $conO, the first virtual console. It assumes that the virtual consoles 
" represent tty devices 0,7 and 8. 
if eq #t 0000 then 
slay sh t=7 -q -s 
if eq #? 0000 then 
ontty 7 sh 
endif 

slay sh t=8 -q -s 
if eq #? 0000 then 
ontty 8 sh 
endif 
endif 


See Also: 

TSK 


[SLAY] 


Utilities 




SLEEP - Sleep for a number of seconds 

Syntax: 

sleep time 


time - Number of seconds to sleep. 

Examples: 

sleep 60 

Description: 

SLEEP suspends execution for time seconds. It is useful in shell files where a delay 

is needed. For example 

"Take a snap shot of all users signed on every 10 minutes. 

:loop 

sleep 600 
who net »users 
goto loop 

The SLEEP command requires that the timer administrator be running. 


timer & 

See Also: 

TIMER 
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SLICE - Set the timeslice rate 


slice [ numjicks [tick_size]] 



numjicks - Number of clock ticks to allow a 

task to run before timeslicing (1..255). 

The default is 1. 

tickjize - Time duration represented by each clock 

tick. Valid numbers are 1,2, 5,10,25 or 50 
milliseconds. The default is 50. 



slice 20 50 - Timeslice every 1 second 

slice 50 1 - Timeslice every 1/20 second, but provide 

a fast timer tick rate of 1 millisecond. 

Description: 

SLICE allows the rate at which QNX will timeslice tasks to be altered. A large 
timeslice count will allow each task to have a large amount of processor time 
before being interrupted by the operating system to run a new task. Large timeslice 
counts favor tasks which require a lot of processor time and which perform little 
I/O. 

Small timeslice values improve interactive response. 

The default value of 1 results in task switching at least as fast as every 50 msec 
(1/20 sec), which usually provides pleasing interactive response with commands 
such as the editor, while still allowing background tasks a fair percentage of the 
processor. 

User written tasks are able to take advantage of fast timer ticks by setting tick_size 
to a value representing the desired fastjick duration. By requesting timeouts in 
units of tickjize, where tick_size has been appropriately adjusted, short duration 
timeouts can be easily implemented. 
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The current timeslice is displayed by the command: 

tsk info 

See Also: 

TIMER 

npoi/’ 

15fv 
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sort [file ] [options]* 



f =field[ field]* 
l-nn 

i=terminationjoharacters 

+bubble_sort 
+descending 
+float 
+hex 
+integer 
+replace 

-skip_leading_delimiters 
+unique 

Where: 

field is fieldjmmber [. offset [. width]] 

Examples: 

sort malllngjltst 

sort inventory f=l,3.2.2,2,7.1 >$Ipt 
sort data ff t= +r +d -s +u 
sort keyword +b +r 

sort file_list t=/ f=-l 



SORT will sort text files based on fields. Lines can be of varying lengths but 
cannot exceed 300 characters. SORT uses an in-memory sort and is limited to files 
of about 55K characters. For larger files the utility MSORT (merge sort) should be 
considered. 


- Define sort fields (max 20). 

- Max lines to sort (default:1000). 

- Characters which isolate fields. 

- Use bubble sort. 

- Sort in descending order. 

- Fields are floating point numbers. 

- Fields are hexadecimal numbers. 

- Fields are integer numbers. 

- Replace file with sorted output. 

- Don’t ignore leading spaces. 

- Remove duplicate lines. 
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A field is by default assumed to be a string of characters which are delimited by 
spaces or tab characters. The delimiter characters can be changed with the t= 
option. The fields can be specified with the f= option, otherwise sorting will be 
based on field 1 ONLY. The sorting is based on the ASCII values of the characters 
in the file unless the +f, +i or +h options are used. If a one of these numeric op- 
tions is specified all fields are considered numeric. To sort on a mix of fields you 
should run several sorts. For example: 

sort file f=l,2 +r , 

sort file f=3 +f +r 


The order and definition of the fields is specified with the f= option. If the field 
number is negative it is taken as the nth field from the right (not the left). A value 
of -1 with a terminator of V 5 allow you to sort a list of pathnames (output of FILES 
command) by their filename only. An offset nn (if given) allows the first nn 
characters of the field to be ignored in the comparison. If a width is given as well, 
then only a maximum of that many characters will be compared. Offset and width 
allow sorting of files which have well defined formats. 

If no input file is specified, the SORT utility will take its input from the standard 
input. The default output of the SORT utility is the standard output. This can be 
redirected to a file or device such as the line printer if desired. The +r option 
causes the output of the sort to replace the contents of the original file instead of 
sending the output to the standard output. 

The sorted output will normally be in ascending order. This can be reversed to 
descending order by specifying +d. 

The -s option allows the user to suspend the automatic skipping of leading fill 
characters. This is particularly useful if the user wishes to distinguish between lines 
which start with fill characters (eg. spaces) and those which do not. 

The +b option will specify that a bubble sort rather than the much faster shell sort 
be used. Bubble sorts have the advantage that order is preserved for identical items. 
This may be important for sorting keyword or "index" files. 

See Also: 

MSORT 
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SP ATCH - Full screen patch utility 



spatch file filename 
spafch disk drive block 
spatch mem segment offset 



spatch file /cmds/ls 
spatch disk 1 1 
spatch mem hOOO 0 



SPATCH is a utility that allows full screen editing of files, disk blocks and 
memory. The screen will display a 16 by 16 (256) byte image of the data being 
examined, similar to that shown below: 
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The menu at the top of the screen can be used to select one of the options listed 
below. You can either position the inverse cursor to the desired menu item with the 
arrow keys and type Enter, or simply type the first letter of the command. 

EDIT 

Enter the data area. The TAB key will switch between hex and character data 
entry. The SELECT (large +) key will return you to the menu. The changed data 

is NOT updated to the disk or memory. 

NEXT 

Move forward 256 bytes. The PgDn key may also be used. 

PREY 

Move backward 256 bytes. The PgUp key may also be used. 

HOME 

Go to the the start of the file, disk or memory. The Home key may also be used. 

GOTO ^ _ 

You will be prompted for an address, 1 ne type of address will depend on the the 

source of the data (file, disk, mem) and the address type. Moving past end-of-file 
in a FILE may produce unexpected results. 

FIND 

You will be prompted for a pattern to search for. The pattern may consist of single 
characters or two hex digits separated by a space. 

61 62 63 d e - match the 5 characters ’abcde’ 

a b c d e - match the 5 characters ’abcde 5 

Typing any key during the search will stop it. CONTINUE 

Find the next occurrence of the last pattern found. Usually used after a FIND when 

searching. 

SAVE 

Save the current screen back to the source. Without issuing this command all 
changes made using EDIT will be lost as soon as you leave the current screen of 
data. 

ADDR 

Toggle through three address types. 

Absolute - Default for FILE 

Disk BlockiOffset - Default for DISK 
Segment:Offset - Default for MEM 
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QUIT 

Leave spatch. 

See Also: 

DUMP 

DDUMP 

PATCH 


[SPATCH] 
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SPLIT - Split a file into one or more files 


Syntax: 

split [outputJile\* [s=size[ 9 size]*[.]] [<inputJile] 



output Jile - One or more output files 
s =size[...] - Define number of lines to put into each 

output file (default: 200) 
input Jile - Source file which is being split 

Examples: 

spilt small i sma'n2 s=iuGu ciarge 

split filel file2 file3 file4 excess <massive s=100 9 20O,1OO 

split firstlOO nextlOO <big s=100 9 100. 



SPLIT allows files to be split into several smaller files. Normally, the file will be 
split every size lines, with the excess going into the last output file. The input file is 
the standard input which should normally be redirected from the file which is to be 
split. 

In the first example above, the first 1000 lines of the file "large" will be placed into 
the file "smalll", and the remaining lines will all be placed into "small2". 

In the second example, the first 100 lines of "massive" will be directed into "filel", 
the next 200 will go to "file2", the next 100 into "file3", and the remainder will end 
up in "file4". 

The 3rd example will place the first 100 lines of "big" into "firstlOO" and the next 
100 lines into "nextlOO". Since the size list ended in a period (.), the remaining 
characters are discarded. 

SPLIT will only split text files with lines no longer than 1000 characters, and has a 
limit of 40 output files. 
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See Also: 

CAT 
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- Spool files to a printer 


Syntax: 


spooler d -device [p -name] [t =imp dir! ] [+clrhouse] 8c 
OR 

spooler 55 c -command" [p=name] [i=tmp_dirl] [+clrhouse] & 


spool [name] submit [filenamelx-filename] [options] 

spool [name] cancel spool Jd 

spool [name] hold [next] 

spool [name] continue 

spool [name] move spool Jd position 

spool [name] query 

spool [name] stop 

spool [name] abort 

spool [name] kick 

Options: 


+clrhouse - If a clearing house is installed on the network, 
this option will cause the spooler to use it. 
c -command- Name the command used to process and output the file, 
(default: spooler prints file). 

d -device - Name the device to which the spooler is to output, 
p -name - Spooler task number/name to use (default 0). 

May be a digit (0-9) or an 8 character name, 
t =tmp_dir - Automatically delete any files which are in this 
directory after printing. This should be a fully 
specified pathname, including node number if necessary. 
x-filename - Index file containing a list of files to spool. 
filename - The name of the file to spool. 
options - Arguments to pass to command. 


spool Jd - A spool-id displayed by the QUERY option. 

position - The position in the spool queue. 


Examples: 


spooler c=list & - Create spooler using LIST, 

spooler p=nec d=$lpt & - Create spooler with name "nec". 

spool su test.c - List file ’test.c’. 
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spool sit x=cfiles 

- List files named in ’efiles’. 

spool sis sales +e s=6 w=80 

- List file ’sales’ with options to list. 

spool qu 

- Query spooled files. 

spool ca 24 

- Cancel spool file #24. 

spool mo 23 1 

- Move spool file #23 to the 


first position. 

spool 1 qu 

- Query files spooled to spooler 1, 

spool nee qu 

- Query files spooled to spooler "nec" 

spool hold next 

- Finish current list then hold. 

spool CO 

- Continue printing. 



The SPOOL command is the user interface to the SPOOLER task in the system. To 

start the SPOOLER task you must run it in background. If you wish to spool to 
more than one printer you must run one SPOOLER for each printer. If you do not 
specify the spooler name/number it will default to 0. 

The SPOOLER may be invoked with the name of a command to run (c=) for each 
file printed. This will typically be the LIST command. If you do not specify a 
command the files will simply be printed to the standard output (or a named device 
using the d= option) with no attempt at formatting or pagination of the data. The 
SPOOLER will typically be run on the local machine which contains the printer. It 
will register a network wide, global name which will be queried by the SPOOL 
command to locate the SPOOLER. The TSK command may be used to print all 
global names in the system. 

tsk names 

You can use the SPOOLER and SPOOL command for purposes other than 
printing. For example, you might wish to serialize compiles. This would provide a 
batch processing mode under QNX. 

The subcommands to SPOOL are listed below. Any subcommand may contain a 
spooler number n, to indicate one of several SPOOLER tasks in the system. By 
default SPOOLER 0 will be assumed. Only the first two letters of a subcommand 
need be specified. 

ABORT 

Abort the SPOOLER task immediately. The current file being printed will stop 
and all spooled requests which have not yet been printed will be lost. 


[SPOOL] 
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CANCEL 

Cancel the request to print the file with the indicated spool Jd. The spool-id is 
listed by the QUERY subcommand. 

CONTINUE 

Continue printing after a HOLD. 

HOLD 

Hold the printing of files. If the optional next argument is specified the cuirent file 
will print to completion before the hold takes affect. Otherwise, the hold will be 
immediate. Once held, printing can be restarted by using the CONTINUE 
subcommand. 

KICK 

Kick the spooler onto the next print request. Any request currently being printed 
will be aborted. 

QUERY 

Query all files awaiting print. 

MOVE 

Move the file with the indicated spool-id to a new position in the queue. The 
spool-id is listed by the QUERY subcommand. 

STOP 

Stop the spooler after the current file is printed. All queued requests will be lost. 

SUBMIT 

Submit a file to the spooler for printing. The command arguments will depend on 
the print command invoked by that SPOOLER command. This will typically be 
the LIST command. Only the name of the file is submitted, not its contents. You 
should wait until the file is actually printed before deleting it. 

See Also: 

COPY 

LIST 

SPOOLDEV 

CLRHOUSE 
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SPOOLDEV - Create a Spooling pseudo-Device 

Syntax: 

spooldev [p =port] [f =configJile] [P=priority] & 

Options: 

p=port - Port to attach to for timeouts. If not specified, the first 

available port will be used, 
f -configjile - File to read configuration from. 

P= priority - Priority to run the specified command at. This option is 
particularly useful for use with QDOS. 

Examples: 

spooldev 8l 
spooldev p=22 & 

spooldev f=/config/spool.config.3 & 

Description: 

SPOOLDEV is an optional system administrator which implements spooling 

devices in QMX. Whereas physical devices have hardware associated with them 
(such as serial ports), a spooling device is a logical device which becomes the 

interface between a program and the print spool queue(s). Anything written to a 
spool device ends up in a temporary file, which will be processed by a user 
specified command when the file is closed. This command will typically submit 
the file to the spool queue using the SPOOL command. 

SPOOLDEV is typically invoked with the f= option, naming a file which contains 
the specifications for the pseudo-devices which will be created. The syntax of 
each line of the file is: 

devjiame [command [arguments [directory [timeout]]]] 

The devjiame is the name by which that spooling device will be known in QNX. 
It is limited to 5 characters drawn from the set of (a-z,A-Z). Numbers may not be 
used. The name may optionally be preceded by a dollar sign ($) in the file. If not 
present, a dollar sign is assumed. 


[SPOOLDEV] 
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The command is used to process the spool file after the spooling device is closed. 
Typically, it looks like: 

"spool submit" 

with the command surrounded by double-quotes ("). This is to "protect" the 
embedded space between the words of the command. The default, if the user 
enters a null command (""), is "spool submit". 

The arguments are used as options to the command to control the appearance of 
the printed output. An example of this is shown later. 

The directory is where SPOOLDEV writes the temporary files prior to actually 
submitting them for printing. The default, if the user enters a null directory (" "), is 
"/spool". 

The timeout field is optional. If you do not wish to support timeouts, specify 0, or 
omit the field. This field specifies the amount of time in seconds, that output must 
stop before SPOOLDEV will force a close of a spool file and process it. This 
option is designed for applications which open a device for a long period of time 
and submit several "print" jobs without opening and closing the device around each 
job. A classic example of this is the optional QDOS package. QDOS opens the 
printer and leaves it open, although multiple print "jobs" may come from the DOS 
programs run under it. 

A reasonable value for the timeout would be 30 seconds or more, on the theory that 
if any program pauses for that length of time while printing, it has probably 
finished. 

Each field may be separated by one or more spaces or tab characters. If there are 
embedded spaces in a field (such as the command or argument string), the field 
must be enclosed in double quotes ("). 

If SPOOLDEV is invoked without a configuration file specified, it is the same as 

invoking it with a configuration file containing the following entry: 

$spool "spool submit" "" /spool 0 

The following example will help to illustrate the use of configuration files. It 
implements a logical device which connects to a Postscript laser printer. These 
printers do not except simple text but Postscript programs as input. It is therefore 
necessary to take text output and turn it into a program which will then drive the 
laser printer. QNX provides a command called LPS which does just that and we 
will use it in this example. 
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Line 1 interfaces to a simple dot matrix printer. Line 2 interfaces to a postscript 

printer and uses the Courier font. Line 3 interfaces to the same postscript printer 
except it prints two pages side by side in landscape mode using the Times-Roman 
font. It is useful for producing program listings. 

$lpt "spool su" 

$laser spool Jist "f=0 p=8 +p” limp 30 

$laseri spool Jist ,f f=4 c=2 p=6 +1 +p” /Imp 30 

In the above example, spool Jist is a shell file which interfaces with the Postscript 

laser printer, as shown below: 

setvar = si [l]5:/tmp/ps.tmp.#n#c 
Ips #* +pc >#sl 
spool nee su #sl >$null 
Fill #1 

The keyword "nee" indicates that the spooler associated with the NEC laser printer 

is to be used (see the SPOOL command). See the LPS utility documentation for 
details about PostScript Laser printers. 

If a user then executes the following command: 

cp report $Iaser 

or 

cp programs $laserl 

the following command will be executed in the background, after the text is fully 
written and die device closed, or no data is written for more than 30 seconds: 

spool list Itmplfile f=0 p=8 +p 
or 

spooljist Itmplfile f=4 c=2 p=6 +1 +p 

where file is replaced with the name of the temporary file created by SPOOLDEV. 

SPOOLDEV does not erase the temporary file. It doesn’t know when the 
command which it invokes is finished with the file. It is up to the invoked 
command to erase it when done. 

In the above example, the shell file will erase the temporary file created by 
SPOOLDEV. The SPOOLER, if started with proper options, such as: 

spooler ”c=cp >$mdm H t=[l]5:/tmp/ & 
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will automatically erase the second temporary file after printing it. 

The user may specify over-riding timeouts and/or arguments when he names the 
spool-device. These are given as extensions to the device name as shown below: 

dev_name[.timeout][,arguments] 

For example: 

copy newfile $laser.5,+d 

specifies a 5 second timeout and an additional "+d" argument when the temporary 
file is sent to the spool queue. 

One final example may prove useful. In a multi-user system, it is sometimes 
necessary to set up the parallel printer as,a spooled device, but allow existing 
applications that write to $lpt to continue to work. If you place the following lines 
in your sys.init./m file: 

stty n=$prt >$lpt 
spooler d=$prt t=/spool & 
spooldev f=/config/spooLinit 

and the file /config/spool.init looks like this: 

$lpt 

then anything written to die device $lpt (formerly the parallel printer) will be 
placed on the spool queue, eliminating multi-user printer contention. The printer 

port ($lpt) was renamed to $prt so that the system may differentiate between the 
physical printer (which SPOOLER wEl write to) and die logical printer which 

applications wiE write to. 

To run SPOOLDEV, the Timer Administrator must first be started, 
timer & 

See Also: 

LIST SPOOL SPOOLER TIMER 
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STTY - Set TTY options 

Syntax: 


st ty ■ [options]* [>device] [ <device ] 

Options: 


+echo - Turn on echoing of input (default). 

-echo - Turn off echoing. 

+efunc - Precede each function and cursor key code with a hex FF. 

-efunc - Do not prefix function and cursor keys (default). 

•fedit - Perform line editing (default). 

-edit - Unbuffered, non-edited input mode. 

+etab - Expand TAB into spaces on output (default). 

-etab - TABS are not expanded. 

+ers - Expand RS (newline) into CR/LF on output (default). 

-ers - RS not expanded. 

+edei - Expand DEL into BS,SPACE,BS on output (default). 

-edel - DEL not expanded. 

+fix - Restore all options to their default values. 

+FIX - Restore all options and control characters to default values, 

•figate - Turn on input gate (default). 

-igate - Turn off input gate. 

+inapcr - Map CR into RS (newline) on input (default). 

-mapcr - CR not mapped. 

•fhangup - Allow hangup exceptions to be generated when carrier detect 
drops. 

-hangup - Disallow hangup exceptions (default). 

+hflow - Support flow control with hardware. 

-hflow - Support flow control with XON/XQFF (CTL-Q/CTL-S) protocol 

(default). 

+hold - Freeze tasks when switching to another virtual console. 

-hold - Don’t freeze tasks when switching to another console (default). 

+iflow - Enable flow control of input. 

-iflow - Disable input flow control (default). 

+ofiow - Enable flow control of output (default). 

-oflow - Disable output flow control. 

•flock - Allow only one task at a time to open for write. 

-lock - Allow multiple tasks to open for write (default). 


+monocurs - Perform cursor handling for the console as if the display adaptor 
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-monocurs 

+noboot 

-noboot 

+nocolour 

-nocolour 

+noswitch 


-noswitch 

+paged 

-paged 

+poll 

-poll 

-i-split 


-split 

ptirae=« 


page=w 

rows=« 

cols=n 


break =hh 
esc =hh 
rub=M 
cait=M 
eot =hh 
ins =hh 

del=M 

up=M 


was a monochrome adaptor. Video cards which allow the use of 
color software on monochrome monitors may require this option to 
be set. 

- Perform cursor handling appropriate to the type of display adaptor 
installed. This mode is the default. 

- Forbid users from rebooting from keyboard. 

- Allow users to reboot from keyboard (default). 

- Suppress colour output for black/white monitors which are 
connected to colour cards. 

- Allow colour output (default). 

- Suppress console switching with the control - Alt key 
combinations. Programs can still output <Escape> and a console 
number from 1 to n to switch consoles under program control. 

- Allow console switching with the control - Alt key combinations. 

- Turn on paged flag. 

- Turn off paged flag. 

- Poll line printer (default). 

- Printer uses interrupts. See 

- Cause the serial port handling within QNX to use only the RTS and 
CTS lines to implement hardware flow control. This frees the DTR 
and DSR signals for other uses. 

- Cause the serial port handling within QNX to use all four hardware 
flow control signals ( RTS, CTS, DTR, DSR ). This is the default. 

- Set parallel printer poll period. The default value for this setting is 
1 millisecond (expressed as 1000 microseconds ). Different 
printers will require that this value be adjusted so that a better 
output rate can be achieved. 

- Define page size (default: 0 - no pagination). 

- Set number of rows displayed on the console. On an EGA display 
adaptor with the EGA graphics library mounted, a rows=4J option 
is supported, allowing a 80 column by 43 line display. 

- Set number of columns displayed on the console. If the display 
adaptor and mounted graphics library allow, a 132 column mode 
could be selected with a co!s=iJ2 option. 

- Define input character which causes break (default: Ctrl-C). 

- Define input char which escapes to new shell (default: Ctrl-Z). 

- Define RUB OUT character (default: 7F hex). 

- Define CANCEL (line erase) character (default: Ctrl-X). 

- Define character which causes EOF (default: Ctrl-D). 

- Define INSERT character (default: Ins on console, Ctrl-N on 
terminal). 

- Define DELETE character (default: Del on console, Ctrl-K on 
terminal). 

- Define character which recalls previous line (default: up-arrow on 
console, Ctrl-U on terminal). 
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down=M 
left =hh 
right =hh 

type=n 


ioport =hh - 

bmd-rate - 
par =parity - 
stop =/2 

bits=a 

inton=n 

intoff=n 

intpri=« 

intcp=^rc,^ 


m=name 


Define character which recalls next line (default: down-arrow on 
console, LF on terminal). 

Define character which moves cursor left (default: left-arrow on 
console, BS on terminal). 

Define character which moves cursor right (default: right-arrow on 
console, none on terminal). 

Set console type. 

1 - fast colour (don’t wait for retrace) 

2 - colour 

3 - monochrome 

Define the I/O port of device controller or memory segment for 
console display. 

Define baud rate (default: 1200). 

Define parity (odd, even, none, space, mark) (default: none). 

Define number of stop bits (default: 1). 

Number of data bits (default: 8). 

Enable interrupt n (2..15). 

Disable interrupt n. 

Define which interrupt has the highest priority. 

- Copy interrupt vector src to vector dst. This option is used to 
allow previously unused interrupt vectors to be set to point to 
existing interrupt handlers. For example, to allow interrupt 5 on an 
AT to be used for a serial port (as are interrupts 3 and 4 ) the 
following would be used: 

stty Intcp=4 ? 5 

Change name of device ("$" optional). 


stty baud=9600 par=even stop=l bits=8 >$mdm 
stty -f-oflow +ers -edel -igate -{-poll >[7]$ipt 
stty page=24 >$con 
stty <$mdm 


STTY allows the characteristics of a device to be modified. The features which are 
supported by the QNX device drivers can be enabled or disabled to better support a 
particular device or terminal. Device dependent parameters such as baud rate and 
transmit parity can also be altered with STTY. If no arguments are given, then 
STTY will display the current options which apply to die specified input device as 
shown in the last example. 
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Line editing features can be changed to please the user. For example, the back- 
arrow key is used on the IBM keyboard as a RUBOUT character. If an ASCII 
terminal is connected to the system, the Backspace key or some other key may be 
more appropriate (note that any character but ASCII DEL will not "erase" input 
characters from the display). Similarly, the CANCEL key may be defined as a key 
which clears a line on a particular terminal. 

The newline character which is used by the QNX operating system is an ASCII 
Record Separator (RS, hex IE). When CR is typed on a terminal, it will normally 
be mapped into a RS (+mapcr). On output, RS is normally expanded into CR/LF 
(-fers). The RS character is used within files to separate lines (records) and is 
referenced in "C" programs as "\n". 

The BREAK, ESCAPE, LEFT, RIGHT, UP, DOWN, INSERT, DELETE, 
RUBOUT, CANCEL, and EOT characters all have special meaning to the 
operating system. The features supported by these characters can be turned off by 
setting these fields to zero in the device table. These characters also lose their 
meaning if the EDIT option is turned off. 

The BREAK key causes an interruption (break) of a running program which results 
in the program being terminated if it is not prepared to handle breaks. The 
ESCAPE key causes a program to be temporarily suspended, and allows the user to 
type in commands to a new SHELL before the suspended program is resumed. 

EOT will indicate end-of-file to a program reading from the terminal. 

The UP and DOWN keys allow a user to "step" through the input buffer, one line 
at a time. UP will go the the previous line, DOWN to the next (in case you have 
"over shot" the line you are looking for). The LEFT and RIGHT keys allow you to 
move your cursor left and right over a line of text to perform line editing. 

RUBOUT will erase the last character on the line. CANCEL will erase the entire 
line. The INSERT character toggles insert mode for the line currently being 
entered. Further characters will be inserted before the character at the cursor until 
INSERT is again detected. The DELETE character will delete the character at the 
cursor. 


When the EDIT option is turned off, the operating system stops supporting line 
editing and all typed characters are passed directly to user programs without delay. 
The following options and special characters are only valid when EDIT is on: 


Options 

igate 


Special Characters 


esc 

eot 

left 

rubout 

ins 

right 

cancel 

id 

up 

break 


down 
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Input flow control (iflow) is only supported when both EDIT and ECHO are 
disabled (such as in TALK). 

IOPORT is the I/O address of the control port(s) which .are used by die operating 

system to communicate with a device. Asynchronous terminals and parallel 
printers use this field. In the case of console displays, this field is the segment of 
the display memory. 

The default type for a colour card is TYPE=2 which will cause QNX to wait for 
horizontal retrace before writing characters to the screen. This eliminates "flash" 
on the screen for some colour cards. Specifying TYPE=1 for colour consoles will 
stop QNX from waiting for horizontal retrace. This will result in much faster 
display updates, especially in the editor, for cards which do not have the flash 
problem. TYPE=3 is used for monochrome cards. TYPE=0 means that no monitor 
is installed. 

INTON allows a hardware interrupt to be recognized by the operating system (an 
interrupt handler must be available to service the request). INTOFF disables the 
interrupt. 

See Also: 

MOUNT 

NACC 
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STYPE - Type arguments on the terminal (no CR/LF) 


Syntax: 

stype [arguments]* 

Examples: 

stype Compiling... 

Description: 

STYPE will echo its arguments to the terminal. STYPE may be used within 
command files to display progress information. No trailing CR/LF is added, so 
many consecutive STYPE commands will all print on the same line. Use TYPE to 
finish with a CR/LF. 

STYPE is a local command which is implemented by the SHELL and therefore 
does not require a command to be loaded from disk. A side effect of having the 
SHELL implement the command is that output cannot be redirected. 

See Also: 

ECHO . 

TYPE 
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TBACKUP - Archive files to QIC tape(s) (QIC02 controllers) 

Syntax; 

tbackup COnfig c =dma_channel i=ioport u=a\e\i 
tbackup INit ["v=volume_name"] 

tbackup Files [archjdir] [+summary] [+[-verbose] 

tbackup NAme 

tbackup SAve save_spec* [-fall] [-clr] [l=levels] [options]* 

tbackup REstore [disk_dir[,arch_dir]] [-create] [options]* [+Newer] [+01der] 

tbackup [drive] VErify [disk_dir[,archjiir]] [options]* 

tbackup [drive] TEst (** some QIC02 controllers only **) 

save_spec: disk_dir[,arch_dir] x=indexJile filename[,arch_dir] 

options: +pause -verbose -ftension -flist-only +640k +|-hog +old 
pf-Wfile_pattern pd =[]dir_pattern pp =[]path_pattern 
-fbefore d -dd-mm-yy i=hh:mm:ss (Use digits) 

+Force (allow use of non-floppy disks) 

%-group m -member 
h=number_64k_segments_to_hog 
terror Jile 

"v-volume jiame" (Use quotes if name contains spaces) 



The TBACKUP command is used to archive files to one or more QIC tapes. This 
command will allow a single backup to span multiple tapes, so that files larger than 
the tape media may also be saved to tape. Each time a file is saved it is appended to 
the end of the archive which may span many tapes. Earlier versions of the same 
file will NOT be overwritten. You may restore any version of a file on the archive. 

When performing a backup that spans tapes, TBACKUP will prompt for new tapes 
as required. The CRON utility should also be investigated, as CRON can cause 
tape backups to automatically occur overnight. 
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TBACKUP 


There are many options for this command and to properly use it, the Floppy and 
Tape Backup technical note at the back of this manual should be read. 

See Also: 

BACKUP CRON FBACKUP 
Floppy and Tape Backup Technical Note 
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TCAP - Manage terminal capability database 

Syntax: 


tcap append tcapjile [name] [f-database] 
tcap copy name newjiame [f =database] 
tcap create [ numjiodes ] [f-database] 
tcap delete name [occurrence] [f -database] 
tcap define name [f-database] 
tcap keys [f -database] 
tcap list [f -database] 
tcap query [f -database] 

tcap set name [f-database] 

OR 

tset name 

Options: 

tcapjile - TCAP database to append from, 
f -database - TCAP database to use 

(default: /config/tcap.dbase). 
name - Entry within the database. 

newjiame - Name of a new entry. 
numjiodes - Maximum number of nodes in network 
(omit for non-networked QNX). 
occurrence - Which of several entries with the 
same name to use. 

Examples: 

tcap set qex 

tset qnxs 

tcap define vtlOO 

tcap copy qnxs vt52 

tcap append old.tcap.dbase vtlOO 

Description: 


[TCAP] 
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TCAP is a data base describing the capabilities of terminals connected to QNX. It 
is used by commands such as ED and MAIL to determine the escape sequences 
required to move the cursor, turn on attributes, recognize function keys etc... 

The TCAP database file contains information about every terminal on every node 
in the network. A terminal type need only be SET once into the database. Once set, 
all full-screen applications should work properly on that terminal. 

The data base is kept in a file called ’tcap.dbase’ under the directory ’config’. 

/config/tcap.dbase 

This file is maintained by the TCAP command. A different database may be 
selected by using the f= option. This is often useful when testing a new terminal 
entry before committing it to the system TCAP database. 

Three of the standard entries in the tcap.dbase file begin with the letters "QNX". 
They should be used in the following circumstances: 

qnx - For the consoles. If you are on the console and your tcap entry is not set, it 
will default to qnx. This setting lets the term() functions use high speed 
video calls. The QNX terminal characteristics are fully supported. 

Remote execution when invoked from the console, will behave like a qnxt 
setting even if the console is set to qnx. This is because high speed video 
calls only work on a local machine. 

qnxs -This entry is used when a user is communicating to a QNX system using 

TALK. Since TALK does not send an FF character to precede function key 
codes, it does not fully support the QNX terminal characteristics. With this 
tcap setting, the term_key() library will insert an FF when the 4-efuncs op¬ 
tion is enabled. In this way, programs like ED which use the FF character to 
distinguish between data and commands will be able to work. Any data 
which has the value of a function key will be taken as a command, due to 
the automatic insertion of the FF. The major disadvantage to using qnxs is 
that there is no means to enter foreign language characters. 

This setting will throw away FF’s if they come in because term_key() is 
generating them on its own based on the value of the data received, so if you 
have a QNX compatible terminal you should avoid using this mode. 

qnxt - Used when communicating with a QNX compatible terminal to another 
QNX system through a serial line. This setting assumes that the terminal 
fully supports the QNX terminal characteristics (including colour). To take 
full advantage of QTALK and QTERM, this setting should be used. There 
are other terminals on the market which also support this tcap setting. 
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Setting your tcap entry to qnxs or qnxt will never go through high speed video 
calls when using the term() functions. 

APPEND 

This command will append the terminal entries in a specified data file to the data 
file in ’/config/tcap.dbase’. For example, assume that you have just received a tcap 
data file from a friend which contains several terminal definitions which you wish 
to use. The APPEND command may be used to append the new definitions to the 
end of your tcap data file. This might result in multiple definitions for the same 
terminal. You can remove a multiple definition using the DELETE command. If a 
name is specified, then only that entry will be copied over. 

The APPEND command can also be used to change the number of node-id’s 
supported. For example, to change the number of node ids to 12 you might enter 
the following sequence of commands. 

chattr n=oldtcap.dfoase /config/tcap.dbase 
tcap create 12 

tcap append /config/oldtcap.dbase 

COPY 

This command will make a copy of an existing terminal entry. This is useful when 
defining a new terminal which is substantially the same as an existing terminal. 
After the copy you would use the DEFINE command to make and changes to the 
new entry. 

CREATE 

This command will create the file ’/config/tcap.dbase’. The numjiodes parameter 
is used by the networking version of QNX. It should be set to the node-id of the 
highest node in the network. A value of zero may be used for non-networked 
versions of QNX, or the field can be omitted entirely. 

DEFINE 

This command is used to define new terminal definitions and modify existing 
definitions. The terminal capabilities are entered into several full screen menus. 
Each menu is responsible for one particular aspect of a terminal definition. The 
editor documentation contains a section on terminals which may give further 
insight into its operation. 
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When creating a new terminal definition, menu 1 should be completed on another 
terminal which has an existing TCAP definition (like the console). After saving it 
away you may wish to complete the definition on the terminal being defined. This 
will allow you to type in the special keys on the terminal rather than having to 
enter a series of escape sequences. The TCAP program uses the direct cursor 
information in menu 1 to position the menu on the screen. It makes use of NO 
other terminal capability. 

Upon entering each menu you will be prompted for an action. Enter the first letter 
of a command to select it. 


CHANGE 

NEXT 

PREY 

ABORT 

SAVE 


Enter the current menu for changes 

Goto the next menu 

Goto the previous menu 

Exit TCAP without saving any changes 

Exit TCAP and save any changes 


The CHANGE command will move you cursor to the first menu field. When 
positioned at the start of a menu field you may enter a 


carriage return 
space 
the letter E 
the letter R 
the character \ 


goto next field 

goto previous field 

erase current field 

return to the menu 

take the next character as data 


Any other character will be taken as data. The current field will be 
erased and the typed character entered as data into the field. Each 
successive character will be entered as data until 


1. The maximum field length is exceeded. 

2. A carriage return which was not preceded by a 
backslash (\) is entered. 


The cursor will then be positioned at the next field. If the field prompt ends with a 
colon (:) then ASCII input is expected. If the field prompt ends with an equal sign 
(=) then numeric input is expected. All numeric input is assumed to be decimal. 

The menu for box characters and input keys will be initialized to default values 
when you create a new terminal entry. These may be changed to more closely 
accommodate your terminal. For the input key escape sequences you should use 
particular care to avoid identical escape sequences for more than one key. For 
example, the default value for the Page Up key is a Ctrl-b. If your terminal 
generated a Ctrl-b as a leadin for its functions keys you will have to change the 
default for Page Up to something else. As another example, some terminals return 
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a TAB character for their right arrow key. In this case you will have to redefine the 
TAB key to be something like an ESC t or you will be unable to enter tabs. 

DEFAULT KEY DEFINITIONS 


Alternate - ESC a 


Up Arrow 
Down Arrow 
Left Arrow 
Right Arrow 


Ctrlu 

Ctrlj or Linefeed 
Ctrlh or Backspace 
Ctrl r 


Home - ESC h 

End - ESC e 

PageUp - Ctrl a 

Page Down - Ctrl b 


Insert 

Delete 

Rubout 

Erase line 

Select 

Cancel 

Help 

Show 

Tab 

Tab to begin 
Tab to end 


Ctrln 

Ctrlk 

Delete or Rubout 
Ctrlx 
ESC CR 
ESC - 
ESC? 

ESCs 

Ctrli or Tab 
ESC TAB b 
ESC TAB e 


Alternate - ESC a 

FI to F10 - ESC 1 to ESC 0 

Fllto F20 - ESC! to ESC) 


NOTE; The following arc die translations which are done for the function keys: 


TCAP entry 

Actual term keyO value 

FI toFlO 

= FI to 

F10 

Fll toF20 

= CNTL FI to 

CNTL F10 

Alternate FI toFlO 

= SHIFT FI to 

SHIFT F10 

Alternate Fll toF20 

= ALT FI to 

ALT F10 


DELETE 


[TCAP] 
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This command will delete the terminal entry specified. The terminal name 
specified must be in the data base. If the occurrence option is specified, then the 
n’th occurrence of a terminal entry will be deleted. This option is useful when 
multiple occurrences of a single terminal exist within the teap data file. 

KEYS 

This command will display the escape sequence for the special keys. These may 
be generated automatically by keys on the keyboard or entered manually as multi¬ 
character sequences. 

LIST 

This command will list the names of all terminals in the data base. 

QUERY 

This command will list the name of your active terminal entry. It should match the 
physical terminal which you are connected to. 

SIT ' ‘ ; ' 

This command will change your active terminal entry to the terminal specified. 
The terminal name specified must be in the data base. 

The TSET compand is provided to allow non super-users to set terminal types. It 
is functionally Equivalent to the TCAP SET command, but does not require the 
user to be a super-user. 

See Also: 

TSET 
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TIMER - Implement timing facility in QNX 

Syntax: 


timer [no_account__entries] & 

Options: 


no_account_entries - maximum number of queued timer requests. 
Default is 10. 


Description: 

TIMER implements a timing facility in QNX. It is required by many utilities and 

3rd party applications. Unless you are absolutely certain that you don’t need it, 

you should be running TIMER. TIMER is usually started from the sys.init at boot 

time, and always left running. 

If you ever do need to terminate TIMER, use the SLAY command: 
slay timer 


See Also: 

CLRHOUSE 

CRON 

LOCKER 

QCP 

SLEEP 

SLICE 

SPOOLDEV 


[TIMER] 


Utilities 


TSET - Set terminal type 

Syntax: 

tset [terminal_type] 

Description: 

TSET allows the user to define query or define which type of terminal is in use for 
the current $tty device. For example, if a user was logged into a QNX machine 
from a vtlOO terminal, the command: 

tset vtlOO 

would allow QNX to recognize the terminal type so that QNX full screen applica¬ 
tions would be able to operate correctly. This example assumes that a vtlOO 
terminal type is defined in the file /config/tcap.dbase. 

Typing the command: 

tset 

would cause the TSET command to display what the currently defined terminal 
type is. 

Note that the TCAP command could also perform this operation, but the user of 
the TCAP command must usually be a super-user because the TCAP command 
also allows the contents of the /config/tcap.dbase file to be modified. The TSET 
command is usable by a non-super user because it does not modify the 
/config/tcap.dbase file. 

See Also: 

TCAP 
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TSK - Display task information 



tsk [f={cmoprstJ] [i=tty] [n=userid\ 

tsk code [p -program} 
tsk info 
tsk mem tid ... 
tsk names 

tsk size [i-tty] [u-userid] [p=program] 

tsk ports 
tsk tree [+tid] 

tsk users [t -tty] [u -userid} [p -program] 

tsk vcs 

tsk who tid ... 

options: +qnx -header +physical n -node s =sorfield 



-header 

+physical 

+qnx 


f={cmoprst} 

n=node 

s-sortfield 


t -tty 
u -userid 
p=prograrn 

tid 


Don’t include a header. 

Display memory as 24 bit addresses. Selectors in protected 
mode are mapped to real physical memory addresses. 

Use the QNX line drawing set when the tree option is used. 
This is the default on the console but must be requested on a 
terminal. 

Select a set of fields of information to be displayed. Each 

letter included represents a field. 

Obtain information from the indicated node rather than the 
local node. 

Sort the lines based upon information in the indicated field. 
Each field is a column separated by blanks. The fields are 
numbered as s=l (first), s=2 (second),... 

Only display tasks associated with the indicated tty. 

Only display tasks associated with the indicated userid. 

Only display information associated with the program task. 
Display information on the indicated task. 
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TSK 

Examples: 

tsk 

tsk t=3 
tsk u=bill 

tsk mem 
tsk mein 30c 
tsk Info 
tsk tree n=7 

tsk vcs 

Description: 

The TSK command allows the user to obtain a "snapshot" of the tasks which are 
currently in existence. If present, the keyword after the command allows you to 
select different types of information and different views of the information 
displayed. You need only type the first two characters of a keyword. 

There are several options common to all forms of the command. The n -node 

option obtains information on another node in the network. The default is to obtain 
information on the current node. The s =sorfield option allows you to sort the 
displayed lines of information based upon a field. You could sort by tty, task id, 
state, code size ... The -f physical option maps 286/386 protected mode selectors 
into real 24 bit memory addresses. 

TSK 

When invoked without a keyword TSK will list the name of all tasks which are 
currently active. The task-id (tid), state, priority, user-number, and associated tty 
are displayed for each task as well as the father-son relationship of the tasks. 
Priorities range from 1 to 15 with 1 being the highest. The task flags field contains 
letters to indicate the following: 

A - Administrator. 

C - Concurrent execution. 

D- Doomed. 

E - Escaped shell. 

H- To be Held. 

L ■» Locked in memory. 

N - New task entry in the process of being created. 

P - Privileged. 

The f={cmoprst} allows you to select which type of information you wish 
displayed. Each letter specified includes a field of information as follows. 


- Display a brief summary of all the tasks in the system. 

- Display a listing of all tasks associated with tty 3. 

- Display a listing of all tasks associated with userid bill. 
- Display the free memory in the system. 

- Display any extra segments used by task (Tid) 30c. 

- Display system configuration information. 

- Display task tree on node 7. 

- Display virtual circuits to other nodes. 
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c - 

m- 

o - 

P - 

r - 
s - 

t - 
u - 


Number of programs sharing this code segment and its Code flags. 
Memory (code/data) used. 

Ownership (group/member). 

Program name and task id. 

Relationships (father/brother/son). 

State Information (state/blockedon/priority/fiags). 

Tty. 

Userid. 


eg: tsk f=pu (display program names and userids) 


You may wish to create a shell command to invoke TSK with your favorite 
options. 


TSK CODE 

Display information on each code segment running in the system. The programs 
name and the number of links (programs sharing the code segment) to the program 
are displayed. The flags field contains letters to indicate the following: 


F - Uses Floating point (8087). 
H- Loaded in high memory. 

L - Locked in memory. 

O- Change Owner. 

P - Privileged. 

R- Remote creates ok. 

S - Shareable. 


TSK INFO 

Displays information on QNX itself. This includes the version number and the 
date the operating system was created. Maximums for a number of items are 
displayed including number of tasks and files. The flags field contains letters to 
indicate the following: 

D - Memory below 1 Meg reserved for DOS. 

F - 8087 installed (float). 

L- Large file system supported. 

M- Memory manager task running. 

P - Password protection enabled. 

R - Remote creates allowed for non super-users. 

S - Automatic sharing of code segments enabled. 


TSK MEM 

Display information on extra segment memory usage. If no arguments are 
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provided then the system memory free list is displayed. If you provide one or 
more task id’s then the extra memory segments allocated by those tasks is 
displayed. 

TSK NAMES 

Display registered names in the system. Both names registered on the global name 
server and names registered on the local machine are listed. 

TSK SIZE 

Display information similar to that shown when TSK is invoked without a 
keyword, only replace the father/brother/son information with the tasks sizes. 

TSK PORTS 

Display which ports are in use and the tasks which have attached to them. 

TSK TREE 

Display a graph showing the relationship of tasks running in the system. The tty is 
displayed at the end of each line. The +tid option will include the task id with the 
name of each task in the displayed graph.. You may select a subset of tasks to 
match using the i-tty or u -userid options. On the console the line drawing 
characters are used while on a terminal +’s, I’s and -’s are used. If your terminal 
supports the console line drawing character set you can force it to be used with the 
+qnx option. 

TSK USERS 

TSK will list the name of all tasks which are currently active. The task-id (tid), 
userid, state, priority, user-number, and associated tty are displayed for each task. 

TSK VCS 

Display virtual circuits existing between this node and other nodes in the network. 
The display shows each local task id and program which has a virtual circuit to 
another node and task id. The virtual id’s and the size of the virtual circuit is also 
displayed. You can obtain more information on the task at the far end of the 
virtual circuit using the WHO subcommand and providing the local vid as an 
argument. 

TSK WHO 

Display the tty, program name and userid running the indicated task. If you type in 
a virtual id (vid) then information on the remote real task is displayed. 
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TYPE - Type arguments 

Syntax: 


type 

type text 

• This is a local shell command • 

Description: 

The arguments following the command are displayed on the terminal, followed by 
a carriage return. This is often used within command files to display progress 
messages. 

See Also: 

ECHO 


[TYPE] 
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TZSET - Display or set timezone offset 



tzset [[+-]hour[:min]] 



hour - 0-12 
min - 0-59 

Examples: 


tzset 
tzset +5 
tzset -3:30 



If no arguments are given, the TZSET command allows the user to display the 
timezone offset on their terminal. The timezone offset is specified as a number of 
hours and minutes, plus or minus, from Greenwich Mean Time (GMT). This offset 
is used to adjust the internal time, which is maintained in GMT, to local time for 
display purposes. 

When changing the timezone, the hour is entered first (optionally preceeded by a 
plus or minus; plus is assumed). The hour may be followed by a colon (:) and a 

number of minutes (which must be a multiple of 15) for die few places in the world 

which are in a timezone that is not on the hour (Newfoundland, Canada for 
example).' 

If you are in a location which periodically adjusts its clocks (for example, Daylight 
Savings Time), simply adjust the timezone offset given to TZSET to maintain the 
correct local time. 

See Also: 

CLOCK DATE ' RTC 
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UNPACK - Unpack a packed file 

Syntax: 

unpack file* [options]* 

OR 

unpack <infile >outfile [options]* 

Options: 

■ 4 -display - Force output to the screen. 

-remove - Suppress the removal of input files. 

^verbose - Display status messages. 

-time - Retain original file time. Set to current time by default. 

Examples: 

unpack - Unpack all packed files 

in current directory 
unpack <packed_text >text 

Description: 

UNPACK expands packed files into exact duplicates of the original. UNPACK 
operates on files which have been created with the PACK utility. 

When the first form of UNPACK is used each file will be replaced by a file with 
the same name and the jl removed. The packed file will by default be removed. 
You can suppress the removal by specifying the -remove option. 

When the second form of UNPACK is used it will read from the standard input and 
write to the standard output. In this case the input file will never be removed and 
you have control over the name of the output file. The -fdisplay will force all 
output to the screen. The input packed files will not be removed. If more than one 
file is specified they will be appended together. If you were on the console the 
following two command would be the same: 

unpack file >$e©n 

unpack file +display 
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This option is typically used to quickly examine the contents of a packed file. 
If the +verbose option is specified each file will be printed as it is unpacked. 

See Also: 

PACK 


[UNPACK] 
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W C - Word count 

Syntax: 


wc | file]* [-chars] [-lines] [-words] [-verbose] 

Options: 

file - Name of a file to count. If omitted 
the standard input is used. 

-chars - Don’t display the number of characters. 

-lines - Don’t display the number of lines. 

-words - Don’t display the number of words. 

-verbose - Don’t display the file name and omit 
descriptive text. 

Examples: 

wc teste 

wc *.c «w 

wc inventory mailingjist -c -v 

Description: 

WC will count the total number of characters, lines and words in each of the given 
files. The number of lines and words is only meaningful for text files. A word is a 
maximal string of characters delimited by spaces, tabs or newlines. 

If more than one filename is given, then WC will also report the total number of 
characters, lines and words in all the files. 

See Also: 

SIZE 


[WC] 


Utilities 



WHO - Who is logged-in to the system 

Syntax: 

who [ami I net I node*] [options]* 

Options: 

am i - Display who you are. 

net - Display all users in the network. 

node - Display all users on this node. 

-header - Suppress column header. 

-[-system - Display system owned tasks. 

-verbose - Display only owner, tty and task name. 

Examples: 

who 

who am i 

who net +§ 

who 3 
who 3 5 7 

Description: 

The WHO command will display the users which are logged on to the system. The 
output will be of the form. 

Node User TTY Idle-Time Sign-On-Time Flags Command 

4 opr 0 0:00:49 Nov-23 5:21 pm — sh 

& dtdodge 4 0:02:45 Nov-23 5:06 pm sh 

If invoked with no arguments, WHO will display all users logged-in to your 
machine. The am i option is useful to find out who is logged on to an unoccupied 
machine or a second window on the console. The net option will list all users 
logged on to all machines in the network. 

The NODE field will only be displayed when running the network version of 

QNX. 
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A field of dashes (— --) for the time indicates that someone forgot to set the date in 
the system. 

The idle time field displays how long it has been since a character was received by 
that particular tty. This field is particularly useful for the detection of users who 
have been idle long enough that they should be logged off. 

The flags field indicates that a message is waiting to be printed on that users 

console. 

A - An appointment was changed 

B - An APB (all points bulletin) 

C - Chat request 
M - A MAIL WAITING message 

See Also: 

LOGIN 

NET 
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ws - Walk directory Structure executing a command 

Syntax: 

ws [directory ["command... 11 ]] [options]* 

Options: 

dc=delete_char - This character when present in command will delete the 
previous character of the expanded string, (default is a 
backquote) 

pc =path_char - This character when present in command will be replaced 

by the current pathname. If the path_char is followed by a 
question mark, then the two character sequence will be 
replaced with input prompted for from the standard input. 

If the path_char is followed by another path_char then 
only the filename and not a complete pathname will be 
replaced. This is sometimes useful when +replace is NOT 
specified but you still want the relative name, (default is an 
at-sign @) 

d -date - Match only those files which have changed since this date. 

Date is of the form dd-mm-yy. (default is 01-Jan-80) 

t =time - Match only those files which have changed since this time 

on the given date. Time is in the 24 hour format hh:mm:ss. 
(default is 0:0:0) 

1 ^levels - Specifies how many levels down from the indicated 

directory will be searched. The default is 1=1 and will 
cause only files at the current level to be searched, not files 
under subdirectories. 

g =group - Indicates that only files whose group number matches 

group will be selected. 

m -member - Indicates that only files whose group member number 

matches member will be selected. 

p =[ h ]pattern - Indicates that only files whose name match this pattern 

will be selected. Up to ten p= options are allowed, in 
which case files which match ANY of these patterns will 
be copied. Also, if the pattern is preceded by an up- arrow 
( A ), then files which match this pattern will NOT be 
selected. 

+abort - If a command returns a non-zero status then WS will abort. 

+before - Changes the meaning of the time and date options to mean 
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4-directory 

4-error 


blocked 

-locked 

+modified 

-modified 

4-query 


4-relative 


-verbose 

Examples: 


before. The default is now or after. 

Selects directories rather than files. 

If a command returns a non-zero status, a prompt to 
continue will be displayed, (default is to ignore returned 
status) 

Match only files which are BUSY. 

Match only files which are not BUSY. 

Match only files which have been modified and not 
backed up using the BACKUP command. 

Match only files which have been not been modified. 
Before executing each command a prompt will be issued 
requesting permission to execute. If option verbose is set 
(default) then the entire command line will be prompted, 
otherwise only the selected pathname is printed. A single 
5 y 5 will execute while anything else will skip to the next 
pathname. 

The WS command will usually generate complete 
pathnames from the indicated directory. This option will 
cause WS to do a CD command when it moves to each 
new directory and the pathname will be the simple 
filename at this directory. 

Suppress the printing of each command before it is 
executed. 


ws "frel - Remove all files at current directory, 

ws /user/bill "frel 1=20 

- Remove all files owned by bill, 
ws /user/bill "drel 1=20 +d 

- Remove all directories owned by bill, 

ws "chattr n=@? p=*data* 

- Change the name of all files containing the string "data" to 
a new name which will be prompted for. 

ws "ed p=*.c d=3/l/83 

- Edit all C programs which were changed on Ian 3,1983. 
ws 2tl "type -v p=xyz 1=12 

- Search all of disk 2 looking for the file xyz. If found, print 
its complete pathname. 


WS is a utility which increases the power and scope of existing QNX commands. It 
is a very powerful command and should be carefully studied. You may rarely need 
it, but when you do, it will be of untold value! 
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The simplest form of the command is: 

ws "command arguments" 

which will execute the command in double quotes on each file in the current 
directory. The double quotes are necessary. Any occurrence of the AT-SIGN 
character (@) will be replaced by the current filename. For example: 

ws ’’type @" - Type name of each file in current directory 

ws ”frel - Release each file in current directory 

A number of options may follow the command. The two most common being 
•fquery and -verbose. The query option will prompt you for each possible execu¬ 
tion of the command. A single "y" will execute the command, anything else will 
skip execution and proceed to the next. The -verbose option suppresses the 
printing of each command before execution. 

WS will not normally descend to subdirectories in the current directory. This can 
be overridden by specifying the number of directories to descend using the \~levels 
option. The following example will release all files under the directory "Aiser/biH" 
including all subdirectories. The directories are then removed. These two 
commands have effectively released all a users’ files, perhaps in preparation of 
removing his user id. 

ws /user/joe ”frel 1=100 - Release all files 

ws /user/joe ”drel +d 1=100 - Release directories 

Note that in this case a particular directory was specified and in the second 
example the +directory option matched directories, NOT files. 

The time and date options allow the selection of files based upon their last change. 
The default will typically select all files. The following command would 
recompile all C source files which were changed today (read up on the MAKE 
command for a better method). 

ws "ce-c @" p=*.c d= 1=5 

Note that a null string for the date defaults to today. 

The p =[ h ]pattern option follows the same syntax as the BACKUP command and it 
should be referred to for wildcard character definitions. 

The AT-SIGN prompt (@?) is provided to increase the flexibility of the WS 
command. There is no limit (within reason) to the number of @? prompts you may 
have on a command line. For example 
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ws "type 

will prompt for each of the five arguments. Note that the @ does not need to be 
delimited by spaces. This is a silly example in that it will select each file in the 
current directory but does not expand it on the command line. The more realistic 
example below allows the super user to interactively set the ownership on each 
user directory 

ws /user "chattr @ o=@?" +q 

The + relative option will cause WS to issue a CD command before entering each 
subdirectory. The pathnames expanded by the AT-sign (@) will contain the last 
component of the full pathname. This can best be understood with an example. 

ws hi "type 1=10 - Type complete pathnames. 

and 

ws hi "type +r 1=10 - Type simple file names. 

All examples above have contained a command and some have contained an 
overriding directory as their first argument. 

If neither is specified then WS will operate on the current directory and prompt 
for command lines from the standard input. Each input line will be executed on all 
selected files and the user will then be prompted for another command. An end-of- 
file (Ctrl-D) will terminate the command. 

If a directory is specified then the syntax requires you to enter a command. If the 
command is an empty string then you will be prompted as above. 

ws ’ Prompt for commands and operate 

on current directory. 

ws /user/bill "" - Prompt and operate on /user/bill 


WS could be used as a filter in which it was piped a series of commands. The 
following simple example assumes that the file my_cmds contains a list of 
commands you wish executed on all files ending in M .c" at the current directory. 

ws p=*.c <my_cmds 


See Also: 

BACKUP EO MAKE 
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XLAT - Translate Characters 

Syntax: 


xlat xfile [+raw] [+wildcard] [<input JUe] [>output Jtle ] 

Options: 

+raw - Turn off output character mappings (ERS, EDEL, 
ETAB). This only affects output to a device. 

^wildcard - Allows the use of the *?’ charcater to match any single 
char. This is useful for removing escape sequences from 
log files. 



xlat qume.xlat </expl/inform >$lpt 

Description: 

XLAT will translate single characters or multi-character sequences found in 
input Jile based on the translations specified in xfile. 

The translation file specified by xfile consists of one or more translate entries with 
optional comments. A translate entry has the form: 

input_seq output_seq [aU_output_seq] 

where each translate entry is on a separate line, inputjseq, outputjseq and 
altj>utput_seq have the form: 

char [,char]* 

char may be specified as an actual character, two hex digits, or a carat ( A ) followed 
by an actual character. The last case will result in a control character if (and only 
if) the actual character is alphabetic (a-z or A-Z), else the actual character will be 
used (this can be useful for entering a comma (,) or carat ( A ), otherwise the hex 
value could be given). A comma (,) is used to separate characters and white space 
(spaces or tabs) is used to separate sequences. 
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If the alt_output_seq is given (it normally is not) then input jeq will toggle 
between the two possible output sequences. 

The following xlat table will convert all record separators, tabs and runs of two 
spaces to a single space. Because only one pass is made through the translation 
table, this will not reduce all "white space" to a single space. 

le 20 

09 20 

20 9 20 20 

This table will translate some control characters into their ASCII name with 
alternates for tab and rubout. 

00 < ? N,U,L,> 

04 <,E,G ? T,> 

07 < 9 B ? E 9 L 9 > 

08 < 9 B,S,> 

09 < 9 H,T,> <,T,A,B)> 

0a < ? LjF ? > 

0c <,F,F,> 

Od <,C,R ? > 

11 <,D,C,1>> 

13 <,D,C ? 3,> 

lb < 5 E 9 SjC,> 
le < 5 R,S 5 > 

7f < ? D ? E,L> <,R,U,B)> 

You may wish to create a number of table to convert 


upper case --> lower case 

ascii »-> ebcdic 

QNX escape daisy wheel printer 

sequences escape sequences 
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ZAP - Zap damaged files out of existence 

Syntax: 

zap file 

Examples: 

zap junk 

zap /user/bill/junk 

Description: 

ONLY USE THIS COMMAND TO RELEASE DAMAGED FILES. 

ZAP should be used when a file is known to contain bad disk blocks, or if a file has 

been left in an inconsistent state (FILE BUSY) due to a system crash while a file 

was being written. 

ZAP releases files by clearing the directory entry for that file. The disk blocks used 
by that file are NOT reclaimed. Repeated use of ZAP will therefore reduce the total 
number of disk blocks available to the user. These can be reclaimed by running the 
CHKFSYS utility when the system is idle. 

Normally, a user should use the FREL, DREL, RM or RMDIR commands to 
release files or directories. 

See Also: 

CHATTR DREL RMDIR 

CHKFSYS FREL RM 
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1. INTRODUCTION 

ED is a foil screen editor for both your console and attached terminals. QNX 

Software Systems has structured this documentation into several major sections. 

1. Tutorial Guide This section consists of a conversational introduction to the 

Full Screen Editor. It contains examples which should be 
attempted on your PC as you read. It is highly recom¬ 
mended that all users, regardless of their level of computer 
experience read this guide. The first several pages contain a 
complete reference to all the defined function and cursor 
keys. It will help you correlate the many functions 
available. Upon completion of the guide you should be 
capable of performing most editing tasks. For most users, 
this may be all you need to know about the editor. 

2. Using Terminals This section describes how to configure ED for attached 

terminals. No configuration is necessary for the console. 

3. Reference Manual This section consists of a detailed description of every 

command supported by the editor. You will discover that 
the defined function and cursor keys are in fact im¬ 
plemented as one or more of these commands. Anyone 
who is going to be using the editor on a regular basis should 
read the preliminary sections up to the APPEND command. 
The description of the SUBSTITUTE and GLOBAL com¬ 
mands are also highly recommended. Should you wish to 
define your own fonction key operations then it is impera¬ 
tive that you read and understand ALL sections. 

4 . Defining Macros This section has been written as a tutorial guide in the 

writing of macros. It should be sufficient to get you started. 
However, the best way to learn about macros is to ex¬ 
periment. 
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2. TUTORIAL GUIDE 

The full screen editor is a program which allows you to type in text, edit it and 
save it away in a file. The editor itself treats your text as a series of lines con¬ 
sisting of from 0 to 512 characters. It was designed as a program development 
editor first and a word processor second. 

When operating on text from a file, the editor reads a copy of your file into 
memory (we will call this a buffer). Any changes you make to your file copy (the 
buffer) will not affect the original file until you issue a write command to save 
your buffer. Should you change your mind about saving the particular changes you 
have made, you may exit without saving, or you may reread a copy of the original 


The maximum number of lines you can edit will depend on how long each line is 
and the amount of available memory space. The maximum number of real charac¬ 
ters in a file that may be edited is on the order of 60,000. Larger files must be split 
and if necessary rejoined after editing. 

2.1 Getting Started 

Assume you want to enter some text and save it away in a file. Making sure that 
your commands disk (/cmds) is in one of your drives, enter the command. 

ed 

The editor will load from disk, clear your screen, then present a screen that should 
look like this. 
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status line 
command line 



text area 


The top line of the screen is the status line and provides information about the size 
of your file, where in the file you are currently located, and what editing options 
you have selected. This line is kept up to date by the editor. You may NOT enter 
text into this area. 

The second line of the screen is the command line. It is the area where you may 
type editor commands which are to be executed. On the monochrome display, a 
solid line appears after this line. 

The rest of the screen is for text. If your text is longer than or wider than the 
screen, then this space represents a window into your text. As you progress, you 
will quickly leam how to position your window to view and/or modify any part of 
your file. 

If you wish to exit from the editor, you can quit by typing a ’q’ followed by a car¬ 
riage return on the command line. If you try this later (after some text has been 
entered), you may be greeted with a message indicating that you have changed 
some text but have not saved it away. You can force an exit without saving your 
text by typing a carriage return to clear the error and a ’qq’ followed by a carriage 
return. We mention quitting here to rescue those people who jump in and then get 
called away before they can read the rest of the manual. 

Now that we have our bearings, let’s look a little closer at these three areas. 
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2.1.1 The Status Line 

This line is composed of three parts.’ On the left "Last=0" indicates, that the last 
line of your text is line 0. You therefore have an empty buffer (zero lines). Next 
to this, the numbers in brackets "( 0 , 1 )" indicate the current position of the cursor in 
die file. It is of the form (row, column). The row indicates your current line and 
for all but an empty buffer it will range in value between 1 and Last. On attached 
terminals you may find that the column number does not change. 

Next on the line are your current editing options. A ’+’ after an option indicates 
that the option is ON while a indicates that it is OFF. Some options which are 
meant to catch your attention when ON will display a flashing V. These options. 
may be turned on and off at the command line. Some of the options are also tied in 
with function keys. They are toggled ON/OFF by the indicated key. 

Briefly the options have the following meaning: 


a - Anchor Alt-a 

This option will be better,understood after reading the section, on pattern mat- 
. ching. For now it is enough to know that die editor has the ability to search for 
text strings and leave your cursor at the string matched. Should you specify,, a 
search for the string "mouse" with this option ON (a+), your cursor will be 
anchored to the start of the pattern matched (in this case ’nT). With (a-), the^ 
cursor would be positioned at the character after the matched string "mouse" 
(in this case the character after the V). 

b » Blank Alt-fo 

When viewing a piece of text on the screen, lines appear to be padded with 
blanks to the end of the screen. Since the editor reads files with variable sized 
lines containing 0 (a line containing only a carriage return) to 256 characters, 
you may wonder whether the blanks at the end of the line are REAL or not. 
With (b-f), the editor will allow you to differentiate between real blanks by 
displaying nulls (non-existent characters) as small centered dots. 

c - Command Large PLUS key 

This option indicates whether your active cursor is in the command area (c+) 
or text area (c-). 

d - Dual ■ Alt-d 

This option, like option anchor (a), concerns pattern matching. If OFF (d-) 
then a search for "mouse" would match the string "MOUSE", "MoUse", 
MOUsE and so on in your text. If ON (d+), the pattern matcher differentiates 
between upper and lower case. 
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f - Fill Alt-f 

This option when ON (f+) will cause automatic filling of input lines at your 
defined right margin. The default right margin is column 60. Should you at¬ 
tempt to enter a character in this column then any preceding characters of a 
word will be moved to the next line. Using this option you may enter text 
without ever having to type a carriage return to end each line. This is ex¬ 
tremely useful when entering documentation and letters. 

i - Insert ins key 

With (i+), all characters typed will be inserted before the character at the cur¬ 
rent cursor position. 

j - Justify Alt-j 

This option is used in conjunction with option Fill. When both option fill (f+) 

and option justify (j-f-) are ON then when each line is filled it will also be 
justified. 

1 - Limit Alt-1 

This option will flash (1+) when a tagged operation is being limited between a 

left and right limit 

m- Meta Alt-m 

With (m+), meta characters are enabled during pattern matching. A meta 
character is a character which has special significance to the pattern matcher. 
For instance the character dot (.) is a meta character that will match ANY 
character, not just a dot. This option will be explained in greater detail later. 

n - Newline FI or F2 keys 

Whenever a carriage return is entered in the text area while this option is on, a 
new line will open up after your current line to allow you to type in new text. 
This can be thought of as line insert mode and is similar to character insert 
mode (i). 

s - Save Alt-s 

With (s+), your buffer will be automatically saved in die file "autosave" after 
every 20 Ikes of kput. While writkg to the disk you may still contkue to 
type up to 256 characters per fine, however, your keys will not be echoed 
(shown on the screen) until the write is complete. 

t - Tabs . Alt-t 

This option is similar to option blank (b). Tab characters k your text are ex¬ 
panded kto enough spaces to reach the next tab stop. What may appear as 4 
spaces may only be one Teal* character. Tumkg this option ON (t+) will 
display die actual tab character as a right triangle. With (b+) also on, the 

spaces which pad the tab to the next tab stop will be displayed as centered dots 
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since they do not exist within the buffer. Tabs are characters which are 
heavily used within € programs for indentation. 

w- Wrap Alt-w 

This option allows pattern searches to wrap around from bottom to top or top 
to bottom when ON (w+). If OFF then pattern matching will stop when it 
reaches the last or first line of the buffer. 

2.1.2 The Command Line 

As previously stated, this line is used for entering text to be interpreted by the 
editor as commands. If you have just entered the editor you should have a flashing 
cursor (underline character) on the left margin of your command line. There will 
also be an inactive cursor (rectangular block) in the text area. Whenever you type 
a character (excluding cursor and most function keys) it will appear where the 
active (flashing) cursor is, and the cursor will move to the right. 

Now try to enter a few commands to change your options. Most options are 
enabled by typing 

o<option character>+ 

and disabled by typing 

o<option character>- 

First let’s turn on option blank by typing the string "ob+" followed by a carriage 
return (don’t enter the double quotes). You can turn it off by typing "ob-<CR>" 
where <CR> designates a carriage return. Finally, you can toggle it by typing 
"ob~<CR>". A toggle causes the option to change state. If it was previously OFF 
it will be turned ON and if it was previously ON it will be turned OFF. 

Should you make a typing error you may delete characters by pressing the dark 
grey back-arrow key or may delete the entire line by pressing the Ctrl and X key 
simultaneously. Both of these keys work on the line containing the active cursor 
and are similar to the line editing keys of the command interpreter explained in the 
QNX Operating System manual. 

If you type in an unknown command or do something which causes an error, an 
error message will be displayed on the command line and held until you type a 
carriage return to clear it. Try typing in "abc<CR>" to generate an error, then clear 
it by typing a carriage return. 
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You should NOTE that you may execute any system command while in the editor 
by preceding it with an exclamation mark (!). For example 

!ls 

led anotherfile 

The second example will invoke another copy of the editor. When you leave you 
will return to this editing session, 

2.1.3 Text Area 

It is this area where your text is displayed and may be directly edited. As you have 
seen by setting ’ob+\ the text area is currently empty. We are now going to enter 
some text and follow through some examples to illustrate the function of the 
various cursor and function keys. Option blank should be ON for these exercises 

(b+>. 

2.2 Appending New Text (FI key) 

To enter toe text area wito toe intention or appending new text, you suouiu. press 
the FI key. The cursor in the text area will become active (flashing) and the com¬ 
mand line will be cross-hatched. You will also see option newline enabled (n+) 
and your last and current line on the line will now be (1,1) not (0,1). The dark back 
arrow key and Ctrl X keys behave in the same manner as they did on the control 
line. 

Type in the following text, typing carriage return at the end of each line. We 
apologize to J. R. Tolkien for the misquote. 

Three Rings for the Eleven-kings under the sky, 

Nine for Mortal Men doomed to die, 

One for the Dark Lord on his light throne 
In the Land of Mordor where the shadows lie. 

In the Land of Mordor where the shadows lie. 

After you finish typing you will want to turn off the option newline (n-). This can 
be done by simply pressing the FI key again. FI is a toggle key. Note that option 
newline is disabled (n-) and the cursor is positioned at the current line or the last 
line typed. Please refer to Section 2.7 if you wish to leave the editor and/or save 
your text. 
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FI appends after the current line and F2 inserts before the current line. Now that 
you have some text, let’s experiment with the cursor keys. Using the four arrow 
keys at the right, you can move the cursor anywhere on your text (note: If the 
arrow keys generate numbers, type the Scroll Lock key). Your screen will scroll if 
necessary. You can move off the right of the screen until your status display in¬ 
dicates that you are on column 512. Note that you can’t move above the first line, 
below the last line or to left of the first character. 

Using the arrow keys, position yourself on line 2 directly under the "N" of "Nine". 
Press the F2 key and note that option newline is now on (n+). A new line has 
opened up between line 1 and line 2 and the cursor points at the beginning of this 
new line. Press F2 again and notice how the line will disappear if you decide that 
this is not the place where you want to insert a new line. Press F2 again and type 
in the following: 

Seven for the Dwarf-lords in their halls of stone, 

Now press F2 again to turn off option newline (n-) and use the cursors to position 
yourself on line 5 under the "I” of "In". Type FI (n+) to append lines after line 5 
and type in the following 2 lines: 

One Ring to rule them ail, One Ring to find them, 

One Disk to bring them all and in the darkness bind them 

Now type FI to turn off option newline (n-). The FI and F2 keys behave iden¬ 
tically when leaving newline mode. 

2.4 Using the Del and Back-arrow keys 

Position yourself about 10 spaces to the right of the word "throne" and type a let¬ 
ter. The editor will immediately lengthen your line with blanks so it can place 
your character where requested. You can delete these blanks to restore the text by 
pressing the back-arrow key or positioning yourself just past the "e" of "throne" 
and holding down the Del key. The Del key deletes the character at the cursor 
causing the line to shift over. 

In general, you will find the back-arrow key useful for correcting new text being 
entered, while the Del key is useful for editing existing text. As an added advan¬ 
tage, the Del key saves each character it deletes. Position yourself at the start of a 
line and hold down the Del key. To restore the last deleted characters press the 
Ctrl and the Ins keys simultaneously. By holding this key down you can restore 
the last 256 characters deleted in this editor session. The characters need not be 
restored where they were deleted. They will be restored at the active cursor 



wherever it is, even at the command line. This can be a useful method of moving 
strings of characters. 

Change the word "Eleven" to "Elven" in line 1 by moving the cursor to the second 
"e" and pressing the Del key. Now move to line 7 and position the cursor under the 
"D" in the word "Disk" and change this word to "Ring" by simply typing over it. 

Note that by default, you are always in replace mode. 

2.5 Inserting text using the Ins key 

Now that we can enter new text, replace existing characters, delete characters and 
re-insert deleted characters, it would be nice to complete our capabilities by inser¬ 
ting new characters. 

Move to the word "light" in line 4 and position the cursor under the "1". Change 
this word to "dark" by pressing the Del key 5 times, pressing Ins (i+), typing the 
word "dark" and then pressing the Ins key again to disable insert mode (1-). 

2.6 Other Cursor keys which Simplify Editing 

There are several more cursor keys which will simplify movement through your 
text as follows: 

1. Pressing shift and left tab H ~, will move the cursor to the start of the current line. 

2. Pressing the Ctrl and the right tab will move the cursor to the end of the ^ 
current line. Always press the shift or Ctrl key-first before the appropriate or 
K “. The key by itself is actually the tab key and will place a tab character in 
your text. Tab characters inserted accidentally in your text can be deleted with 
the Del key. 

3. A Ctrl and either the left or right arrow cursor movement keys will step over 
words quickly. They will always stop at the end of a line containing text. The 
keys are symmetrical. If you overshoot, simply go in the opposite direction. 

4. ' A Ctrl and either the up or down arrow cursor movement keys will move your 
cursor up or down four lines. 

To test the other cursor keys, a file exceeding the text area must be used. The file 
/expl/inform (shipped with the QNX operating system on your boot disk) may be 
used as a source of text for exercise two. 
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2.7 Saving your Text 

At any time you may leave the text area and go to the command area by typing the 
large PLUS (+) key on the right hand side of the keyboard. Note that the right and 
left cursor keys, the Del and Ins key will operate on the command line. Other 
cursor keys refer only to the text area. Write your file away by typing: 

w llenarae<CR> - Note that <CR> is the 
carriage return key. 

Do not type <CR>. 

Filename is any valid pathname as explained in the operating system manual. After 
your file has been saved, the editor positions you back in the text area where you 
left off. You can now continue with the rest of the exercises or may leave the editor 
by typing the Large PLUS (+) key again followed by a ’q’. If you modify the file, 
the ’q’ command will not let you quit without saving your changes. If you do not 
wish to save your changes type ’qq’ to force the editor to exit. 

2.8 Exercise 2 

Position the active cursor at the command line using the Large PLUS (+) key and 
enter the command: 

e /expl/inform 

The V command deletes your current buffer and reads the file into the editor 
creating a new buffer. Note that the editor checks to make sure any current file 
you are working on has been saved before proceeding. If you get a warning, type 
carriage return to clear the error and use the ’ee’ command to force the editor to 
load the new file. 

ee /expl/inform 


Your buffer now contains too many lines to display on your screen and some lines 
which are too wide to display in their entirety. You have a window of n lines by m 
characters into your text. Try using your arrow keys to move about the current 
screen. If you attempt to leave the screen it will automatically scroll. If you want 
to move faster remember the Ctrl arrow keys step over words and the Shift and 
Ctrl “* move to the beginning and end of a line. 

Two common reference points in a file are its beginning and end. Press the Home 
key and you will find yourself back at the first line. Press the End key and you will 
find yourself at the last line of your buffer. A Ctrl and the Home or End key will 
move you to the first or last line of your current screen respectively. This means 
that you have a local Home and End as well as a global Home and End. 
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To step through the file a page at a time you can use the PgUp and PgDn keys. 
These keys lock up at the beginning or end of your file buffer. The cursor will be 
left at your defined center line which defaults to line 3. If you prefer it to be the 
first line or another line you can change it by entering command mode (the big V 
key) and typing the view center command: eg "vc <number>" where number is 
between 1 and (screen length - 2) 

To set the defined center line to line 1 enter: 

vcl 

Occasionally you would like to scroll the screen up or down one line without 
moving the cursor from its current screen line position. This can be accomplished 
via the Ctrl-PgUp and Ctrl-PgDn keys. 

When editing programs, one of the greatest virtues of a screen editor is its ability to 
give you context via its full screen display. The unmarked 5 key on the numeric 
keypad is designed to aid you in this respect. If you move the cursor to any line on 
the screen then press the 5 key (termed the center key), your screen will be 

redisplayed with that line positioned at your defined center line. Try positioning 

the cursor on one of the lines at the bottom of the screen and press the 5 key. 

We have now exhausted the supplied cursor movement keys and it is time to ex¬ 
amine the 10 function keys in more detail. QNX Software Systems has found that 
the odd function keys are in general easier to type and where possible has placed 
the more commonly used editing keys on them. 

2.9 More on the FI and F2 keys 

The FI and F2 keys as we have seen toggle the new line mode. While in newline 
mode, you may at any time go to the command area and execute any editor com¬ 
mand or toggle any of the options. This includes setting option newline OFF in¬ 
stead of using the FI or F2 keys as toggle switches. This method of entering new 
lines is different from most editors and much more flexible. You are not locked 
into an append-only mode. 

For example, if you are entering text with option blank off and want to know 
where all your ’’real" blanks are, you can zip up to the command area, turn ON 
option blank (b+) and zip back without leaving the newline mode. This facility 
allows you to write your file occasionally without exiting from newline mode. The 
editor always places you where you left off after your file has been written away. 

Also, suppose you have 5 lines of text in your buffer and are half way through 
adding line 6 when you notice a typing error on line 2. You are free to move im¬ 
mediately to line 2 using the cursor movement keys, correct the error, and return 
again to where you left off on line 6. 
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In an earlier example (Section 23) you inserted a line using the F2 key and turned 
the newline mode off. You then moved the cursor keys to another position and 
appended 2 lines using the FI key. As you will see from the following examples it 
was not necessary to turn the newline mode off between the two steps. Newline 
mode has no effect until you type a carriage return. 

Try double spacing the first few lines of the /expl/inform file. Move to the first 
line of the file by pressing the Home key. Press FI and type a carriage return and 
then move to the start of die second line using the cursor movement keys. Type 
another carriage return and continue appending a few blank lines in this manner. 

You could also try the following: 

1. Appending and inserting text lines in the file. 

2. Correcting and inserting characters in the text using the Del and Ins key. 

3. Combining steps 2 and 3 without leaving newline mode. 

When leaving the newline mode using either the FI or F2 keys, the editor will 
delete the last blank line. Typically when appending text users will enter their last 
line followed by a carriage return. This will open up an unwanted hole which the 
closing FI (or F2) conveniently removes. However, for your protection this 
automatic delete is conditional upon the line being empty. 

2.10 Deleting Lines (F3 key) 

Your file now has a few blank lines which you may wish to delete. F3 is the line 
delete key and will delete the current line. Move the cursor to the start of a blank 
line and press F3. Continue deleting the blank lines in this manner. Now move to 
a line containing text and press F3. If you wish very hard and then press Ctrl F2 
your line will reappear. 

The editor stores deleted lines in a delete buffer. The Ctrl FI will append the last 
deleted single line after the current line and the Ctrl F2 will insert the line before 
the current line. In this case, we inserted the deleted line because the current 
cursor line moved down one line when the F3 key was used. 

If you delete 5 lines you can restore them one by one using Ctrl FI or F2. They can 
be deleted in one text area and "undeleted" into another area. In most cases, this 
can be used as a method of moving lines of text; however, a simpler method of 
. moving blocks of lines using the F7 and F8 keys will be explained later. 
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2.11 Filling Lines (F4 key) 

When in option fill (f+) your lines will be broken on word boundaries based upon 
your current right margin. If at some time in the future you would like to change * 
your right margin and refill your text you can accomplish this using the F4 func¬ 
tion key. It will take the line your cursor is on and all following lines up to: 

1. A blank line which is assumed to be a paragraph separator. 

2. The end of the file, 
whichever occurs first. 

A line may be marked as a paragraph start by typing an Alt-p. A paragraph symbol 
will appear at the END of the line. The Alt-p acts as a toggle allowing you to 
mark/unmark a line. Filling will stop at each paragraph start, that line will be 
indented and filling will then continue until one of the above two conditions is 
reached. The paragraph start is provided as a means to stop filling between two 
consecutive lines. 

If a group of lines have been tagged as described under the F7 key, then only those 

tagged lines will be filled. Filling will step over each paragraph stop as described 

above. 

Lines are filled between your LEFT and RIGHT margins. If option justify (toggle 
with Alt-j) is ON (j+), then the text will also be right justified. 

2.12 Centering Lines (Ctrl-F4 key) 

This key will center the current line between the LEFT and RIGHT margins. Mul¬ 
tiple lines may be centered by tagging them as described under the F7 key. 

2.13 Splitting and Joining Lines (F5/F6 keys) 

Sooner or later you are going to want to split a long line or join two short lines 
together. The F5 key will split a line at the current cursor position into two lines. 
The F6 key will join the cursor line and the following line together. In practice, 
you normally split a line on a space and no longer want the space after the split. 

The F5 key checks if the character under the cursor is a space and if so, deletes it 
before the split. On a join, F6 checks to see if the cursor line ends in a space and, if 
not, appends one before joining. 

If you wish to keep a space on a split or suppress the append of a space on a join, 
then use a Ctrl F5 or a Ctrl F6. These keys make no assumptions; they simply split 
and join. Note that the operations of split and join are symmetrical. Try splitting 
and joining several lines to get used to this function. 
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2.14 Tagging Blocks of Text (F7/F8 keys) 

It is often convenient to tag a group of lines, then select an operation to perform on 
the lines selected. For example, earlier we mentioned a method of deleting a group 
of lines. Although there are several ways of accomplishing this, the most con¬ 
venient way is by a tagged delete. The lines to be deleted are tagged and then 
deleted as a group. 

There are two types of tagging. 

1. Line tagging 

2„ Block (line and column) tagging,, 

2.14.1 Line Tagging 

This is the simpler form and allows you to tag lines in their entirety. The selected 
operation applies to the whole line. For example, to delete a block of lines you 
would locate the first line in the series to be deleted and press the F7 key. The line 
is displayed in reverse-video to indicate that it has been tagged. F7 is another 
toggle key which sets/removes a tag, hence the line could be "untagged" by pres¬ 
sing F7 again. This is a more complex toggle which is also tied into block tagging, 
and you should pause about one second before depressing the key again to untag a 
line. 

Now move the cursor and tag the last line to be deleted using F7. You will notice 
that all of the lines to be deleted in between the tagged lines now show up as 
inverse-video. When you set two tags, aU lines between the two tagged lines are 
treated as a tagged block. To perform the actual delete, press the F8 key (the tag 
operation key). This key will prompt you for a command and typing a "d" will 
delete all the lines as a block. The deleted lines can be restored as a block using 
the Ctrl FI or Ctrl F2 (probably a Ctrl F2 since you would want to insert them 
before the current line). 

You will find that if you delete lines one at a time the editor will restore them one 
at a time and if you delete them as a block they will be restored as a block. This is 
explained in detail in the Reference Manual. 

The tagging of lines may also be used as a method for moving and copying blocks 
of lines. The F8 key has five functions: 

■ d (delete, already explained) 

- m (move) 

- k (kopy) 
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- s (save) 

- p (print lines on $lpt) 

To try the move option, find a small block of text and tag the first and last lines 
using the F7 key. Move the cursor to another place in the text, press F8 and re¬ 
spond to the prompt with an’m’. The tagged block of text will be appended after 
the current cursor line. 

The kopy option is analogous to the move option. Tag a block of lines using the 

F7 keys. Move to the desired location, press F8, enter a ’k’ when prompted and 
the lines will be copied after the current cursor line. The original tagged block of 
text remains unchanged. 

The save option will save the tagged lines into the file Vtmp /group.member 9 , 
where GROUP and MEMBER will be numbers. The saved text may be restored 
later using the SHIFT F8 key. Selecting a line paste (1) will insert the text before 
the line your cursor is on. You may save and restore text between different edit 
sessions and/or consoles. 

The F4 (fill) and Ctrl-F4 (center) keys will operate on tagged lines if any have been 
set. If not they default to the range indicated on the section describing them. 

Some things to remember when using tags: 

1. You are allowed a maximum of two tags at any one time. If you set a third tag, 
then it replaces an existing tag. 

2. Tag operations apply to all lines between two tagged lines. If only one tag is 
set, a tag operation will apply to that line only. 

3. The order in which the tags are set does not matter. 

4. Tags may be removed from your text by: 

(i) performing a tag operation function, 

(ii) using the F7 key as a toggle switch, or 

(iii) typing a Ctrl F7 which removes/resets all tags. 

2.14.2 Block Tagging 

Line tagging is sufficient for most editing tasks. It falls short in those cases where 
you wish to operate on a block of text within a line. This occurs most frequently in 
the preparation of multi-column text. 
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For example, if you wished to move the block of C’s 


AAAAAAA 

AAAAAAA 

AAAAAAA 

AAAAAAA 

DDDDDDD 

DDDDDDD 

DDDDDDD 

DDDDDDD 


BBBBBBB 

BBBBBBB 

BBBBBBB 


CCCCCCC 

CCCCCCC 

CCCCCCC 

CCCCCCC 


UNDER the block of B’s you would need to tag only the C’s, not the A’s and B’s. 
Enter the text above and position yourself on the first character of the first line of 
C’s. Depress the F7 (tag key) twice in rapid succession. The first depression will 
tag the line and the second depression will turn on the block tag feature and set a 
left limit at your cursor. The characters from the first C to the end of your line will 
be displayed in inverse video. 

Now move your cursor to the C in the lower right comer and depress the F7 key 
again. You need only depress it once. This will tag the last line of C’s and set a 
right limit. The block of C’s should now be displayed in inverse video. If you 
wish, you may adjust the line range being tagged or the limits of the tag by moving 
your cursor and typing the F7 key. Unlike line tagging, typing F7 again will not 
remove a block tag. 

Now move your cursor under the first B on the line containing the first row of D’s 
and depress the F8 key. You will be queried with a more extensive list of opera¬ 
tions then a simple line delete. They are 


d - delete 

The tagged block will be deleted. Any text to the right will slide over to the 
left to fill the gap. 


e - erase 

Th e tagged block will be replaced by blanks. In the special case where there is 
' no text to the right of the block then the text is simply deleted. This option 
will maintain column integrity. 

k - kopy 

The tagged block win be copied to the current cursor location. The original 

text is unchanged unless the destination overlaps the tagged block. 

m - move and erase 
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This is a combined KOPY followed by an ERASE. 


M - move and delete 

This is a combined KOPY followed by a DELETE, 
s- save 

The save option will save the tagged text into the file Vtmp /group.member’, 
where group and member will be numbers. The saved text may be restored 
later using the SHIFT F8 key. Selecting a column paste will insert the text at 
your cursor. You may save and restore text between different edit sessions. 

p - print 

Print tagged block on the printer ($lpt). 

Select the’m’ or "M" operation to move the block. 

2.14.3 Insert Mode and Block Move and Copy 

When performing a tagged block MOVE or COPY with option insert off (i-), the 
moved text will simply overiay any cxi&iing lCal. u upiioii Hioci t is encioleci. ly-r j 
then the text will be inserted before the cursor. This can add considerable con¬ 
venience. For example you may move the block of C’s in front of the block of D’s 
by tagging it, enabling option insert, and performing a move to the first character 
of the first line of D’s. You should tag extra spaces to the right so the columns line 
up. After the move, delete the extra block of C’s. It is recommended that you 
always check the state of option insert when performing a tagged block move. 

2.14.4 Re-setting the Last Tagged Lines or Block 

The Ctrl-F7 is a toggle which can be used to retag lines or a block. Depressing it 
with NO tags set will restore the last tags set. Depressing it with tags set will clear 
all tags. 

Tags are set on absolute line and column numbers and inserting or deleting lines 
and characters may cause your tags to move with respect to your text. 

2.15 Re-executing Commands (F9/F10 keys) 

These two keys are used for re-executing command line commands. The F9 key 
will re-execute the last command. F10 will redisplay the last command allowing 
you to edit it, if needed, before typing a carriage return to execute it. These func¬ 
tions will be more useful as you leam more editor commands in the next sections. 
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2.16 Zooming Your Text 

If you have an EGA card and have mounted the EGA library 

mount lib /config/glib.ega Must be executed before 

mounting my consoles 

your console will support 25 by 80 text and 43 by 80 text. Typing Alt z will zoom 

your display between these two modes. It is possible for custom screen drivers to 
be written which support more than two screen sizes. In this case the editor is 
capable of supporting up to 6 different screen sizes. 

When the editor exits it will return your screen to the size it had upon entry. Note 
that outside the editor the STTY command may be used to set your screen size. 

stty rows=43 
stty rows=25 

2.17 Tabs 

The editor has tab stops set every four columns with the first tab set on column 
five. Typing the tab key will enter a tab character at your active cursor. When 
displayed on your screen the tab character will be expanded into the necessary 
number of spaces to move to the next tab stop. Try inserting a few tabs into your 
text. You can display the tab character as a right triangle by turning on option tabs 
(ot+). By also turning on option blank (ob+), padding spaces will be displayed as 
small centered dots since they do not exist within your text. 

Tabs are not treated with any special significance internally. They only affect your 
display and cursor movement on the display. You can not position your cursor on 
the padding spaces following a tab, only on the tab character itself or the first real 
character following it. 

The use of tabs rather than spaces for indentation in structured languages can save 
considerable typing and file space storage on your diskette. 

You can change your tab settings by using the View Tab command. On the com¬ 
mand line type: 

vt2 • Tabs every 2 

vt4 • Tabs every 4 

vt8 • Tabs every 8 
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2.18 Composed Characters 

You may enter composed characters directly into your text. These are discussed in 
the QNX manual in the section on terminal handling. For example, typing: 

Alt (release the key) e 9 produces an e accent aigu 
Alt (release the key) p i produces the symbol pi 
etc... 

2.19 Line Drawing Characters 

You can redefine the Ctrl and Alt cursor keys into line drawing characters by ex¬ 
ecuting a macro file as follows. 

x /cmds/box.macros Enter this within ED on the command line 

R y perimep f by typ inc ^2,eh cursor -key and Alt cirrsor~lcey within the editor 

The Home, PgUp, PgDn, End and 5 key should also be used. Some of the keys will 
move you in the most natural direction for drawing a box, however, the Ctrl down 
arrow will not move beyond the last line of your file buffer. You can press car¬ 
riage return to open up room. 

2.20 Margins 

The editor maintains a left margin which determines the point a carriage return will 
return to and a right margin which determines the point at which filling will occur. 

2.20.1 Moving Your Margins (Shift FI to F6) 

A Shift FI will set your left margin at your current cursor position and a Shift F2 
will set your right margin at your current cursor position. Shift F3 and F4 will 
march your left margin left or right while a Shift F5 and F6 will march your right 
margin left or right. 

2.20.2 Auto Fill and Your Right Margin 

Go to the command area (using the Large (+) key) and enable option fill with the 
command 

of+ 

or toggle it on with the Alt-f key combination. In the text area, append the fol- 
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lowing ten lines (taken from "The Princess Bride" - William Goldman) as one long 
line. Do NOT type a carriage return. 


The year Buttercup was born, the most beautiful 
woman in the world was a French scullery maid named 
Annette. Annette worked in Paris for the Duke and 
Duchess de Guiche, and it did not escape the Duke’s 
notice that someone extraordinary was polishing the 
pewter. The Duke’s notice did not escape the notice of 
the Duchess either, who was not very beautiful and not 
very rich, but plenty smart. The Duchess set about 
studying Annette and shortly found her adversary’s 
tragic flaw. Chocolate. 


You will find that the editor will automatically take any partially typed word and 
move it to the next line when the cursor column exceeds 60, which is your default 
right margin. This feature allows you to type continuously without having to 
closely watch the screen. You can change your right margin using the VIEW 
command which will be described shortly. 

2.20.3 Auto Justify 

Go to the command area and enable option justify with the command 

oj+ 

or toggle it on with the Alt-j key combination. In the text area, append the fol¬ 
lowing lines. 

Prince Humperdinck was shaped like a barrel. His chest was 
a great barrel chest, his thighs mighty barrel thighs. He 
was not tall but he weighed close to 250 pounds, brick hard. 

He walked like a crab, side to side, and probably if he had 
wanted to be a ballet dancer, he would have been doomed to 
a miserable life of endless frustration. 

You will find that the editor automatically justifies each line with your right 
margin when it fills. This option is only active when option fill is enabled. 



A Ctrl-b will begin an indent of four spaces (increase your left margin by four) and 
a Ctrl-e will end an indent (decrease your left margin by four). Append die fol¬ 
lowing 6 lines, holding down the Ctrl and typing a ’b’ or ’e’ for <Ctrl-b> and 
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<ctrl-e>. 


The year Buttercup turned ten, 

<Ctrl-b>the most beautiful woman lived in Bengal, 
<Ctrl-b>the daughter of a successful tea merchant. 
This girl’s name was Aluthra, 

<ctrl-e>and her skin was of a dusky perfection 
<Ctrl-e>unseen in India for eighty years. 


You should note that your left margin only determines the point you will return to 
on a carriage return. You may use your cursor keys to move to the left of an in¬ 
dent. 

Programmers should NOT use this feature for indentation. The TAB key should 
be used instead. The above technique results in large quantities of spaces in your 
files. This will result in larger files and slower compiles. 

2.21 Line Flags 

2.21.1 Overstrike Flag (Alt-o) 

This will flag the end of the current line with a left arrow character. When this line 
is written, the record separator will be replaced by a carriage return. As a result, 
when this line is printed, no linefeed will be issued and the following line will 
over strike this line. This flag is automatically set when reading source lines which 
terminate in carriage returns rather than record separators. This allows reading and 
editing the output of DOC files which have underlining and/or boldfacing. 

2.21.2 Continuation Flag (Alt-c) 

This will flag the end of the current line with a bidirectional arrow character. 

When this line is written, the record separator will be suppressed. As a result, the 
next line will be continued (joined) with this one. When the editor reads a line of 
greater than 512 characters it will automatically split the input line and set this flag 
on the split line. This allows for the editing of files containing very long lines. 

2.21.3 Paragraph Flag (Alt-p) 

This will flag the end of the current line with a paragraph symbol. This is used by 
the fill key (F4). 
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2.22 Some Simple Editor Commands. 

You should now be able to create new files, edit existing files (e filename) and 
write them away (w filename). Up until now you have had little reason to leave 
text mode to go to command mode to execute editor commands. The next sections 
will introduce you to some useful editor commands. 

2.23 Learn Mode 

If you have a sequence of keys which you enter often, you may wish to leam them 
once and assign them to a single key. Let’s assume that you wish to leam the 
string "Copyright © 1983". The next time you are about to enter it, type a ’Ctrl 
Minus’ sign on the keypad and enter a ’Ctrl a’ when prompted for the key to leam. 
Type in your text then signal the end of leam mode by typing a ’Ctrl Break’. From 
this point on each time you enter a ’Ctrl a’ it will be replaced by the learned input 
sequence. 

It is possible to leam very long and complex sequences consisting of text, cursor 
movements and commands. 

2.24 Absolute Line Positioning 

The Home, End, PgUp and PgDn keys allow you a coarse means of moving 
through a buffer, however, if you want to be in the middle of a thousand line buffer 
they are very awkward to use. If you go to the command line and type in the 
number of the line you want to go to (followed by a carriage return to execute) the 
editor takes this as a command to move your cursor to that line. This gives you the 
ability to move through the file in absolute terms. For example, if a compiler is¬ 
sues an error for line 458 of a source file then upon reading that source file with the 
editor you can go right to that line. 

2.25 Simple Pattern Matching 

When editing a file, you often want to be able to say "Find me an occurrence of 
this string" so you can work on it without knowing precisely where it is. This is 
especially tme when working from a paper listing in which you know the text 
string you want to edit, but probably not its line number. In the editor you can find 
a string simply by enclosing it in slashes on the command line. The command 

/son/ 

will cause a search to be made for the string "son". If option dual is off (od-) then 
the matching will be case insensitive and /son/ will match "SON", "SoN", "sON" 
and so on. It will also match a line containing "personal" since it contains an in¬ 
stance of "son". 
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Searching begins at the character AFTER your cursor, resulting in the editor fin¬ 
ding the next occurrence of your pattern. If the editor searches down to the end of 
the buffer without finding your pattern and option wrap is ON (w+) it will continue 
the search at the first line of the buffer and continue until it reaches and tries your 
current line from behind. If your pattern is not found, an error will be generated. 

Assuming you match a line containing your pattern, then that line will become 
your current line and your cursor will either point to the first character of the string 
matched (a+) or the character after this string (a-). The default is option anchor 
enabled (a+); however, if you are adding commas to the end of words you may 
prefer to switch to a-. 

Enclosing a pattern in question marks instead of slashes will cause a search to be 
made backwards through your buffer. Therefore 

?son? 

will search for the first occurrence of the string "son" starting at the character 
before the cursor. If the editor searches backward to the beginning of the buffer 
without finding the pattern and option wrap is ON (w+) it will continue searching 
backwards from the end of the buffer. Again if your pattern is not found an error 
will be generated. 

The editor is careful always to remember the last pattern you specified. Typing 

// 

will cause a search for the last pattern specified. This can save typing when 
looking for multiple occurrences of a long pattern. An even faster method would 
be to use the F9 key to re-execute the last command. 

Up until now we have used the words string and pattern interchangeably. Although 
the editor can search for simple strings of characters like 

/The quick brown fox/ 

they are a subset of a more powerful pattern matching facility. This facility is 
enabled by the option metacharacters (om+) when you define a pattern. When 
enabled the characters., @, $, A , *,/, ?, and [ have a special meaning. For in¬ 
stance, a Y is a pattern which matches any character. The pattern 

/ax/ 

would match an occurrence of a string containing an ’a’ followed by ANY 
character followed by a ’c\ The meanings of these characters are explained in 
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detail in the reference manual (section 3). Unless you intend to read this you 

should turn off option metacharacters (om-) or prefix all special characters with a 
backslash character in your pattern. When prefixed by a backslash the special 
characters mentioned above lose their special meaning. A 

/catU 

will only match the string "cat.” regardless of the state of option m. If you want to 
match a backslash you must type two of them. A 

/a\\b/ 

will match the string "aNb". For non-alphanumerics the rule is simply this. If a 
character is preceded by a ’Y then remove the backslash and take that character 
literally. This allows you to specify a slash in your pattern. A 

/totalVnumber/ 

will match the string ,, total/number ,, . The slash is protected and not taken as the 
pattern delimeter. 

For alphanumerics the rule is slightly more involved. If the two characters fol¬ 
lowing the backslash are hexadecimal (0 to 9 or A to F) then the whole sequence is 
taken as one character which has the hexadecimal value indicated. A 

A§7/ 

is a pattern consisting of the single character whose hexadecimal value is 07. AAz/ 
is just a V while a Abe/ is the character whose hexadecimal value is be. If this 
seems complex or confusing you probably don’t need this ability. Just remember to 
type two back slashes to get one and that you can match a slash (or a ? if you scan 
backwards) by prefixing it with a backslash. 

2.26 File I/O Commands 

As we have already seen, we can read a file into the editors buffer with the ’e’ 

command 

e filename 

ee filename 

and write out our buffer to a file with the ’w’ command, 
w filename 
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Whenever you read a file with the edit command (e) three things actually occur. 

1. Your current buffer is purged. However, your delete buffer is kept, allowing 
you to delete from one file and undelete into another. 

2. The filename you specified is memorized. 

3. The contents of the file are read into your empty buffer. 

In each example we have specified the filename that the command should operate 
upon. This is not always necessary. Should you omit the filename it will default to 
the filename of the last file you specified with your V command. Therefore... 

e report 

followed by a 

w 

will have the write command write to the file "report”. Likewise, an 
e 

will simply re-read the last file edited. This is often used when you bungle some¬ 
thing and want a fresh copy. Note that in this case you will probably have to issue 

an 


ee 

command to indicate that your unsaved buffer should be overwritten. For your 
protection a simple V will not destroy an unsaved buffer. 

If you want to check the name of your current file, you can issue the file command. 

f 

which will display it in the command area. You can change it (or define it) by 
following the command with a filename. 

f filel 

This will define your current filename as "filel". 
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It is often useful to read another file into a non-empty buffer after some specified 
line. This can be accomplished with the Y command. 

r fiie2 - reads file2 into the buffer after 

tlie current line 

The command may be prefixed by a number (or pattern search) to explicitly in¬ 
dicate a particular line. 

lOr filename - reads file2 after the 10th line 
in the text buffer. 

/end/r filename - reads flle2 after the line 

containing the next occurrence 
of "end" in the text buffer. 


The read (Y) command does not affect the current filename. If you do not specify 
a filename after Y the editor will read another copy of the current file into your 
text buffer. 

It is also possible to prefix the write ( ? w s ) command with a line number or range of 
lines to write. 


w filename 
33w filename 
l,10w filename 
#w filename 


all lines are written 
line 33 only is written 
lines 1,10 are written 
all tagged lines are written 


Finally, you can append to a file by specifying the write append command which is 
of the same form as the write command. 

wa filename 


This is useful when you wish to build a new file based upon lines or blocks of lines 
from your current file (or many files). 


l,4w file 
24,30wa file 
#wa file 
e newfile 
l,10wa file 


initialize file with lines 1 through 4 
append lines 24 through 30 
append a group of tagged lines 
read a new file 
append first 10 lines 
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2.27 The View Command 

Users with a colour display can change the colour of the three display areas using 
the view attribute command. 

va <area> <foreground colour> <background colour> 

where: area -> 1 - Status line 

2 - Command line 

3 - Text lines 

colour -> Number between 1 and 15 inclusive 


The colour card has a design characteristic that causes interference (snow, blips 
etc...) when you write to the screen memory. To avoid this it is necessary to wait 
for the horizontal retrace signal before writing characters. This has the side affect 
of slowing down display updates. A number of colour card look-alikes do not 
suffer from this problem and full sp^od up dating Qf the display may b Q restored 
with the stty command system command. 

stty type=l - fast colour card 

stty type=2 - slow colour card 

Do not use these commands on a monochrome card. It is always type 3. 

Users with the improved cards should place this command in their ’/config/sys.init’ 
file. 

2.28 Executing System Commands 

Any QNX command may be executed from within the editor by preceding it with 
an exclamation mark (!). For example: 

!ls 

Ifrel junk 
!ec test & 
led anotherJFile 
Hist this fiie & 

After executing the QNX command, the editor will pause, waiting for the user to 
type carriage-return before redisplaying the screen. If you type two exclamation 
marks (!!) the screen clear and pause will be suppressed allowing you to invoke 
commands via macros in a hidden manner. 
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Note that Ctrl-Z is recognized within the editor and will bring up a new shell al¬ 
lowing you to execute multiple commands. To return to the editor type a Ctrl-D to 
terminate the new shell. 

2.29 Epilogue 

At this point you should be able to perform most editing tasks. However, this 
introduction has hit on only a few of the editor commands and interested users are 
strongly urged to read the reference manual, especially if they are interested in 
defining their own function key operations. 
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3. Using Ed on a Terminal 



When ED is invoked on an attached terminal it opens a file called ’/con- 
fig/tcap.dbase’. This file contains information entries for different types of ter¬ 
minals. The entry for each terminal contains the output escape sequences neces¬ 
sary to: 

1. Move the cursor 

2. Change the text attributes to 

- inverse 

- highlight 

- underline 

- blink 

- colour 

3. Clear 

- the screen 

- to end of line 

- to end of screen 

4. Draw lines and boxes 


The entry also contains the input escape sequences sent by any special keys on the 
terminal’s keyboard. These are typically function and arrow keys. 

You may query the terminals in the database by typing the TCAP command 

tcap list ’ 

and you may query your currently set terminal by typing 

tcap query 

If the query does not agree with your terminal type, you may change it by typing 
tset terminal_name 

where the terminal name must be one of those listed in the database. If your ter¬ 
minal is not in the database, you will have to read the documentation on TCAP for 
defining a new terminal. 
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3.2 Required Terminal Capabilities 

Any terminal which is to be used with ED must support the following capabilities. 

1. Direct Cursor Addressing 

2 . Screen Clearing 

3. Zero width escape sequences 


The last point requires further explanation. On some terminals, an escape se¬ 
quence to turn on inverse video takes up a character position on the line. As a 
result your standard 80 column line will be reduced to 78 columns (one character 
to turn on, and one character to turn off) ED does will NOT work properly on this 
type of primitive terminal. Escape sequences must NOT take any physical room 
on the screen. Fortunately, nearly all terminals work this way. 

Although not required, the following capabilities are recommended 

1. Clear to end of line. 

2„ Insert and delete line. 

3. Inverse video (and to a lesser extent underline). 

4. Up, down, left and right cursor keys. 


The first two will speed up display updates while the third is necessary for 
displaying tagged blocks of text. If your terminal supports Highlighting or under¬ 
line, but not inverse video, then ED will attempt to display tagged areas of text 
using these capabilities. Without cursor keys, the editor may be painful to use. 

You may wish to consider a truly QNX compatible terminal described later in this 
section. 

3.3 Screen Output 

Ed will adjust its output to conform to your terminal’s screen size. Display updates 
will be determined by the baud rate of your attached terminal. This will be con¬ 
siderably slower than running ED on the console. Non-ascii characters 

control : hex 0 to IF 
extended : hex 7E to FF 

will be displayed as a question (?) mark. They are saved and manipulated as the 
characters they really represent. It is only the display which prints them as ques- 
tion marks. 
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Note: on attached terminals, the column position is NOT updated as you move 
your cursor. To force an update you must type the <SHOW> key, which on a PC 
keyboard, is the center key on the numeric keypad 

3.4 Keyboard Input 

It is keyboard input which really differentiates using ED on the console from ED 
on a terminal. The console keyboard is rich in both function and cursor keys. 
Unfortunately, most terminals are rather limited in the special keys that they 
provide. To overcome this it is often necessary to enter a two or three character 
sequence to simulate a single console key. The terminal database defines keys 
according to their function. For example, the large PLUS key on the console key¬ 
board is called the SELECT key. It is used by most applications to leave some 
form of input mode and return back to a command state. This key is very seldom 
found on a terminal, so a default two character sequence of an 

ESC CR - select key input sequence 

is mapped into the code returned by the console SELECT key on input. The fol¬ 
lowing table contains the default mapping supplied by TCAP for a terminal with 
NO special keys what-so-ever. The multi-character input sequences will be 
mapped into the single key codes returned by the console keyboard. Terminals 
which do support special keys may override these default sequences to match those 
generated by its keys. 
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Up Arrow - Ctrl u 
Down Arrow - Ctrl j or Linefeed 
Left Arrow - Ctrl h or Backspace 
Right Arrow - Ctrl r 

Home - ESC h 

End - ESC e 

Page up - Ctrl a 

Page down - Ctrl b 

Insert - Ctrl n 

Delete - Ctrl k 

Rubout - Delete or Rubout 
Erase line - Ctrl x 

Select - ESC CR 

Cancel - ESC - 

Help ' - ESC ? 

Show - ESC s 

Tab - Ctrl i or Tab 

Tab to begin - ESC TAB b 
Tab to end - ESC TAB e 

Alternate - ESC a 

FI to F10 - ESC 1 to ESC 0 

Fll to F20 - ESC ! to ESC ) 


NOTE: The following are the translations which are done for the 
function keys: 

TCAP entry Key value as seen by ED 

FI toFlO = FI to F10 

FI 1 to F20 = CNTLJP1 to CNTL_F10 

Alternate FI toFlO = SHIFTJF1 to SHIFTJFIO 

Alternate FlltoF20 = ALTJFl to ALTJF10 

The ALTERNATE escape sequence may prefix any other escape sequence. It may 
be used to generate the control Arrows, Page up/down, Home and End keys as well 

as another 20 function keys. These correspond to the SHIFT and ALT function 

keys on the keyboard. 
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There is no provision for executing any of the ALT letter keys such as ALT-b to 
turn on option blank. You will have to go to the command line and type the option 
command directly. 

ob+ or ob- 


You may examine the input escape sequences in effect for your terminal by typing 
leap keys 

3.5 QNX Compatible Terminals 

There are several terminals on the market which feature complete QNX com¬ 
patibility. They feature a PC keyboard which generates the same codes as the IBM 
console, and a 25 line display with the full PC character set and QNX escape se¬ 
quences. Phone our Technical Support line for the current list of such terminals. A 
special TCAP entry exists for this type of terminal. 

tset qnxt 
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4. REFERENCE MANUAL 

4.1 The Syntax of Editor Commands 

An editor command is of the form: 

<line range>C<argument>" 

where: <line range> indicates which lines to operate on. 

C is a single character indicating a command. 

<argument> is command specific information. 

4.1.1 Line Range 

The line range specifies which lines the command should operate on. It can consist 
of zero, one or two line addresses. If no range is specified then it will usually 
default to the current line. The current line is the line your cursor is on in the text 
area and will typically be updated by each command to reflect the last line it 
operated on. Check the section on each command for the exact behavior. A <line 
range> is of the form: 

<> 

or <line> 
or <Iinel>,<line2> 
or <linel>;<iine2> 
or * 
or # 

where: <Iine> is the address of a particular line in your 
text buffer. 


The first form in which NO line address is specified will cause the command to 
choose a default line address. If not stated otherwise, the default will be the cur¬ 
rent line. 

The second form indicates that the command is to operate on the specified line 
only. 

The third form indicates that the command should operate on the range of lines 
specified. 
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The fourth form is similar to the third form except that the current line is set to 

<linel> upon encountering the 

The fifth form is an abbreviation for "1,$" which indicates that die command 
should be applied to all lines, ' 

The final form indicates that the command should operate on the tagged lines in 
the buffer. Depending on the number of lines tagged this can result in two forms: 

<line> - only one line tagged 

or <linel>,<!ine2> - two lines tagged 


The elements of a <line range> are line addresses <line> and are composed of: 

<number> This is an ordinary line number referring to the <number>th line 
of the buffer. 

$ This special character refers to the last line of the buffer. 

. This refers to the current line of the buffer. 

@ This refers to the line occupying the currently defined center line. 

& This refers to the top line of your currently displayed screen. 

% This refers to the current line if you are in the text area and line 

zero if you are on die command line. It is often used in macros by 
the ZAP (z) command to operate on the command line. 

/<pattern>/ This is the address of the line which contains an instance of the 
specified pattern. The search for <pattem> will begin at the 
character after the cursor and will continue to the end of the buf¬ 
fer. If no match has been found by that time, and option wrap is 
ON (w+), the search will wrap around to the beginning of the 
buffer and continue looking for <pattem> from line one. If no 
match is found in the entire buffer then an error will be issued. 

^ This line search sets the condition register TRUE if a match is 
found and FALSE if a match is not found. 

?<pattern>? This serves as the line address of the line which contains an in¬ 
stance of the specified pattern. The search for <pattem> will 
begin at the character before the cursor and will go backwards • 
through the buffer wrapping around from the first to last line if 
necessary. If no match is found an error will be issued as above. 
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This line search also sets the condition register to TRUE on a 
match and FALSE on no match. 

Each line address above may be combined with other line addresses using the V 
and keys to form expressions. For example. 

.-Sj.+S - will specify the five lines 

before and after the current line. 

&;.+23 - will specify all lines on the 

current screen. 

?begin?,/end/ - will specify all lines between the 

lines containing the previous "begin” 
and the next "end”. 


If you specify a line address which is outside the buffer you will get an error and 
die command will NOT be executed. The special character OR-BAR (!) can be 
used to limit the preceding line addresses to lie within the buffer (between one and 
$). This is very useful in defining macros. The T operator sets the condition 
register FALSE if the line address falls outside the buffer and needs to be limited. 
For example: 


&;.+23| - is a safer form of the example 

shown above. 


4.1.2 Command Specification Character 

Each major command consists of a single character which has been chosen to 
reflect its nature. For example, the character’d’ was chosen for the delete com¬ 
mand and the character ’w’ was chosen for the write command. This character 
must be in lower case. 

If a command line is entered which contains a <line range> but no command 

44 . 

then the current line is set to the last line address specified. In this case the cursor 
will move to line 44. 



Some commands require extra information to specify their operation. For ex¬ 
ample, the MOVE (m) command requires the specification of the destination line 
address: 



<linel>,<line2>m<line3> 

Other commands like die ZAP (z) command represent a class of commands which 
are specified by sub-command characters. For example: 

zed 

is a zap cursor delete command. The "cd" are subcommands of the zap command 
and will not be interpreted as the major commands V and *d\ This form of sub¬ 
command is used by several editor major commands. 

4.2 Placing Multiple Commands On A Line 

The editor allows you to place more than one command on a line. Each command 
on the line is executed sequentially from left to right. For example: 

ob+ot+ 

will turn on option blank followed by option tab. The command: 

l»4d$d 

will delete lines one through four and then delete the last line. Note that the line 
range only applies to the command that it immediately precedes. Should an error 
occur on any command then execution will be halted and any following commands 
will NOT be executed. 

Some editor commands consume all characters until the end of the line collecting 
their right argument. They must therefore be the last command on any line on 
which they occur. For example 

e filename 

consumes all characters until the end of the line collecting the filename. 



The Full Screen Editor treats a small number of characters as special in certain 
situations. These characters are described in the following subsections. The only 
character you can NOT save in your text is an ascii Null (hexadecimal value 00). 
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43.1 The Newline Character (hexadecimal IE) 

The newline character in QNX is a record separator (hexadecimal value IE). 
Source files separate lines by a single newline character NOT a carriage return 
and/or linefeed. On input, whenever you enter a carriage return (hexadecimal 
value OD) it is mapped into a newline character. 

When the editor reads a file it collects characters up until a newline, replaces the 
newline with a null (hexadecimal value 00) and saves the collected characters as a 
line in your buffer. The point to note is that the newline is NOT saved. It is 
stripped on a read and added to the end of each line when the file is written. 

In the definition of complex macros containing several lines, the lines may be 
separated by either a carriage return OR a record separator. The supplied macro 
file has adopted the convention of using the record separator. 

43.2 The Null Character (hexadecimal 00) 

The Null character (hex 00) is used internally by the editor to delimit strings. It is 
therefore not possible to save this character in your buffer. Should you attempt to 
enter this character, the line (text or command) will be truncated at that point. 

4.3.3 The Meta Characters <5>$ A &.*[ 

When option meta-characters is ON (m+), then these characters have a very special 
meaning when used within patterns (they are special only within patterns). The 
period V for example will match ANY character, not just a period. The meaning 
of these characters is explained in the section on pattern matching. 

43.4 The Backslash Character \ 

The escape character on the command line is the backslash. When it precedes a 
meta character in a pattern it causes that character to be taken literally. That 
character loses any special significance it might have normally had. 

Following a backslash by two hexadecimal characters in a pattern or translate 

string results in a single character with the hexadecimal value specified. For ex¬ 
ample ME is the single character whose hexadecimal value is IE (a record se- 
parator). 

4.3.5 The Tab Character (hexadecimal 09) 

When displayed on your screen this character will be expanded into the necessary 
number of spaces to move to the next tab stop. Tab stops are fixed at every four 
columns with the first stop set on column five. You can display tabs by turning 
ON option tabs display (ot+). 
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Tabs are not treated with any special significance internally. They only affect your 
display and your cursor movement on the display. You can not position your 
cursor on the expanded spaces following the tab, only the tab character itself or the 
real character following it. 

4.3.6 The Command Character (hexadecimal FF) 

On input, the character with hexadecimal value FF will cause all characters up 
until die next record separator (newline) to be collected (no echo) in a hidden 
buffer, then executed as a command. Any current text on the command line is 
NOT affected. This character is used heavily by the translate command when 
defining macros for the various cursor and function command keys. 

This character is only special on input. You can place a hexadecimal FF character 
in your text by using the substitute command and a \ff escape. 

s/CAff/ - replace C with the hexadecimal character FF 

4.3.7 The Recall Character (hexadecimal FE) 

On input, the character with hexadecimal value FE will recall to the command line 
the last command typed. This character is used by the F9 and F10 function keys. 

You can place this character in your text by using the substitute command as 
above. 

4.3.8 The Keyboard Input Character (hexadecimal FD) 

When this character is encountered in a macro, the editor will accept a character 
from the keyboard. If several characters occur in a row, a maximum of that 
number of characters will be accepted. Entering a carriage return will always 
terminate input (skipping any remaining FD’s) and the carriage return will be 
discarded. 

4.3.9 The Macro Disable Character (hexadecimal A3) 

On input, the character with hexadecimal value A3 will prevent the next character 
from being expanded should a translate be in effect for it. For example, the Home 
key has a hexadecimal value of AO, but is translated on input into the three 
character string: 

<command char>l<newline> 

If you would like to prevent this expansion (to enter the key’s value) then you 
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should proceed it with the key on the numeric keypad which generates the code 
for the Macro Disable character. You can of course enter the Macro Disable 
character itself by typing the key twice. 

An alternative method of entering a translated key value would use the compose 
sequence described in the QNX manual for direct hexadecimal input. 



The editor maintains a special register called the condition register which is set to 
TRUE or FALSE by some of the editor commands. This register can be tested by 
the BRANCH (b) command and the UNTIL (u) command to perform conditional 
execution of editor commands. These commands are commonly used in macros. 

4.5 Delete Buffers 

The Editor maintains a buffer for deleted characters and another buffer for deleted 
lines. 

4.5.1 The Character Delete Buffer 

The character delete buffer is arranged as a stack 256 characters long. Adding a 
character to a full buffer will cause the oldest character to be lost. In this manner 
the most recent 256 characters are kept. 

The editor maintains primitive commands for: 

- adding a character to the buffer, 

- removing the last character which was added to the buffer. 

- purging the buffer. 

These primitives are provided by subcommands of the ZAP (z) command. 

The saving of the last deleted character via the Del key is performed by a macro 
which saves the character under the cursor in the character delete buffer before 
deleting it. Likewise, the restoration of a deleted character via the Cntl-Ins key is 
based upon a macro which inserts the last character placed in the delete buffer 
before the current cursor position. 

4.5.2 The Line Delete Buffer 

The editor maintains another buffer in parallel with your text buffer called the line 
delete buffer. This buffer has the same structure as your text buffer, however, it 
can not be displayed or directly operated on by the editor’s many commands. Each 
time you delete a line via the DELETE (d) command it is moved from your text 
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buffer into your line delete buffer. You can restore deleted lines using the special 
forms of the APPEND (a) and INSERT (i) commands which can move lines from 
the delete buffer back to your text buffer. 

The moving of lines between the two buffers is slightly more complicated than is 
indicated above and is best explained by an example. 

If you were to delete 5 lines, one at a time (say via the F3 key) it would be nice if 
you could undelete them one at a time so that the last line deleted was the first line 
restored. This is particularly nice when you delete one line too many and just want 
to restore the last one, not all of them. Conversely, if you were to delete a group of 
100 lines as a block (say via a tagged delete) you do not want to have to restore 
them one at a time but want them restored as a block as well. The above two 
scenarios describe, from a user’s point of view, the editor’s implementation of the 
line delete buffer. Associated with the buffer is a flag which indicates whether the 
buffer contains a series of single line deletes or one block delete. To avoid confu¬ 
sion, the editor will purge the line delete buffer before adding in the following 
circumstances. 

~ i on perrorm a single line cieiefc aoo. tne line ouner contains a oiock delete. 

- You perform a block delete. A block delete always purges the line delete 
buffer before adding the new block. 

Put simply, if you delete lines one at a time, they are undeleted one at a time and if 
you delete a block of lines they are undeleted as a block. Mixing blocks or types is 
prevented by purging before adding, if necessary. 

When working with a very large buffer it is possible for the editor to mn out of 
memory. When this happens it will purge the delete buffer in an attempt to free up 
some space. You will be warned of this by a message on the command line which 
you must clear (like an error) by typing a carriage return. Deleting all lines in a 
file, then attempting to edit another large file will often generate this message. In 
this case you have all of the original file in memory in the line delete buffer and are 
trying to read another large file into the text buffer. They may not both fit! 

4.6 Break Handling 

The editor will terminate any operation gracefully at the earliest possible moment 
after the BREAK (Ctrl Scroll Lock) key is typed. As a result of the break, any 
operation may be incomplete on the range of lines specified for a command, 
however, no line will be left in a partially modified state. Should you break out of 
an EDIT (e), READ (r), or WRITE (w) command you may only move a subset of 
the lines into or out of your buffer to the specified file. 
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After servicing the BREAK the editor will leave you in command state. 

4.7 The Pattern Matcher 

The editor has a very powerful pattern matching facility which will match the class 
of patterns known as regular expressions. Patterns are used for line searches and 
by the GLOBAL (g) and SUBSTITUTE (s) commands. It is the editor’s pattern 
matching facility that gives it flexibility in writing powerful macros. For example, 
the Ctrl left and right arrow keys are implemented by a pattern which searches for 
the next or previous word in your text. We will attempt to describe the patterns 
accepted by the editor in a very rigorous manner. It is assumed that option meta 
characters is ON (m+) during the definition of your pattern. If it is OFF (m-) then 
the editor will only recognize the class of patterns represented by (a) and (b) 
below. 

(a) The simplest pattern is a single character. Such a pattern matches the 
given character in either upper or lower case, unless option dual is ON 
(d+) to make the Pattern Matcher differentiate between cases. 

(b) Patterns arranged adjacently form a single pattern. For example: 

/afoc/ 

matches any string "abc". 

(c) The character 5 A 9 specifies a pattern which matches the null string at the 
beginning of the line. Thus a line search of: 

/ A charm/ 

would match the string "charm" at the beginning of a line. 

(d) The character ’$’ specifies a pattern which matches the null string at the 
end of the line. Thus a line search of: 

/charm$/ 

would match the string "charm" at the end of a line. 

(e) The character V specifies a pattern which matches any character. Thus a 
line search of: 

/charm./ 

would match the string "charm" followed by any character on a line. 
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(f) Any pattern followed by a defines a pattern which matches a string of 

zero or more occurrences of that pattern. Thus: 

lb*l 

matches the strings "b", "bb", "bbb”, etc. In addition, since patterns 
will match zero occurrences of a given pattern "Zb*/" will also match 

The Pattern Matcher will match a construction with the longest 
sequence matching the given pattern beginning in a given column; for 
example, if a line contains the string "bbbbbb", ”/b*/" will match all six 
b’s as a unit, not individually. 

(g) The construction 5, @(<number>) ?5 is a pattern which matches the null 

string immediately before the <number>th column on the line. Thus a 
line search of: 

@(10)charm 

would match the string ’’charm" starting in character position ten on the 
line. 

If <number> is zero or the character V then this pattern will match the 
null string before the current cursor position in the text area. 

If <number> is the character Y then this pattern will match the null 
string before the next TAB stop. This can be used to turn runs of spaces 
into tabs. See the SUBSTITUTE command. 

(h) The construction "^string^’]" matches any one character in string and 
no other. Thus: 

/[0123456789]/ 

is a pattern which will match a single digit. Characters in the square 
brackets are taken literally, without their special meanings; thus: 

nv 

will match the character Y and no other. A sequence of characters may 
be specified by separating the lower and upper character by a dash (-). 
For example: 

/[a-zO-9]/ 

is a pattern which will match any letter or any digit. To match a you 
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may protect it with the backslash (\) character. 


(i) The construction ,, [ A <string>] H matches any one character that is NOT 
in string. Thus: 

/[ A 0-9 ]/ 

is a pattern which will match any character that is not a digit. 

(j) A null pattern 5, // f? is equivalent to die pattern most recently specified 
within the editor. This feature is convenient for searching through a file 

for a particular string. For example, if you are looking for the string 
"hello" you could specify: 

/hello/ 

the first time and: 

// 

on subsequent searches. An even quicker method of performing this 
task would use the F9 key to simply re-execute your line search. 

(k) Any character preceded by the backslash character ’V loses its special 
meaning. Thus: 

A\\ A U $/ 

would match the string "\ A .$". 

4*8 Some Pattern Examples 


/hello/ 

/ A hello/ 

/hello$/ 

/ A hello$/ 

/ *$/ 


will match the string "hello" anywhere on a line, 
will match the string "hello" at the start of a line, 
will match the string "hello" at the end of a line, 
will match a line containing ONLY the string "hello", 
will match all trailing blanks (including zero) on a line. 
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/**$/ 

/[0-9][0-9]*/ 

/[a-z_J[a-z_0-9]*/ 

/@ (10) [0-9]/ 

/ A $/ 

/ A *$/ 
/ A \[a-z][a-z]*/ 


will match all characters (including zero) on a line. 

will match a number like "3", ”862”, etc. 
will match an identifier in the language C. 

- will match a digit in column ten. 

will match an empty line. 

will match a line containing only blanks. 

will match a line starting with a period followed by a name 
(such as a command in die text formatter). 


4.9 Editor Commands 


The following pages contain an alphabetical list of all editor commands. 
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After Current Line 


Syntax: 

<line>a 

<line>a <text> 

<line>ad 

Description: 

The first two forms of this command turn ON option newline (n+) and open 
up a newline after the current line. If the second form with <text> is specified then 
that text will be placed at the start of the newly opened line, this form is often 
used within a GLOBAL (g) command to append a string after a set of matched 
lines. The blank between the ’a’ and <text> is required. 

The third form appends the last deleted line (or range of lines) from the delete 
buffer. Option newline is not affected. 

The append command must be the last command on a line. 

Current Line: 

Set to the address of the new line opened up. 

Condition Register: 

Not affected. 
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4.11 b - Branch 

Syntax: 

b<number> 

b<number>t 

b<number>f 



This command allows you to branch over <number>-l command lines. The 
first form branches unconditionally, the second form branches if the condition 
register is TRUE and the third form branches if the condition register is FALSE. 
The condition register is not affected by the branch. Branches are often used inside 
macros defined by the TRANSLATE ™ command and make little sense when 
executed directly. 

If <number> is zero then the current command line is re-executed. If <number> is 
one, then the rest of the current command line is skipped. If <number> is greater 
than one, then <number>-I command lines will be read and discarded. A com¬ 
mand line is considered as a string of characters terminated by a record separator 
ME). 

The BRANCH command can not be used inside a GLOBAL (g) or UNTIL (u) 
command. 

Current Line: 

Not affected. 

Condition Register: 

Not affected. 
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4.12 c - Change Lines 

Syntax: 

dine range>c 
cline range>c ctext> 

Description: 

This command deletes the specified range of lines from the text buffer and 
places them in the line delete buffer. It then turns ON option newline (n+) and 
opens up one line for input. If the second form with ctext> is specified then that 
text will be placed at the start of the newly opened line. 

The change command is functionally equivalent to a DELETE (d) command fol¬ 
lowed by an INSERT (i) command. 

Current Line: 

Set to the address of the new line opened up. 

Condition Register: 

Not affected. 
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4.13 d - Delete Lines 



dine range>d 



This command deletes the specified range of lines from the text buffer and 

places them in the delete buffer. 

If the dine range> specifies more than one line to be deleted OR the delete buffer 
contains a previous delete of a range of lines, then the delete buffer is purged 
before appending the new lines. 

If a delete of a single line is requested and the delete buffer is empty or contains 
lines which have been deleted one by one, then this new line is inserted at the 
beginning of the delete buffer. 

Current Line* 

Set to the address of the line after the last line deleted. 

Condition Register: 

Not affected. 
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4.14 e - Edit a New File 

Syntax: 

e 

e <filename> 
ee 

ee <filename> 

Description: 

This command deletes the contents of the current buffer (without placing the 
lines in the delete buffer) and reads in the lines associated with the specified file. 

Since the contents of the delete buffer are not affected, you can use it to move lines 

from one file to another by performing a DELETE (d), EDITING (ee) a new file 

and then undeleting the lines into the new file (AD command). 

The first form reads from the currently defined filename while the second form 
reads from the indicated filename and makes that the current filename. Both of 
these will not destroy a non-empty buffer which has been modified. The last two 
forms will edit regardless of the current state of the buffer. 

The current filename can be queried or changed by the FILE (f) command. 

The EDIT command must be the last command on a line. 

The EDIT command can not be used inside a GLOBAL (g) or UNTIL (u) com¬ 
mand. 

Current Line: 

Set to the first line of the buffer. 

Condition Register: 

Not affected. 
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4.15 f - File Query/Set 
Syntax: 

f 

f <filename> 

Description: 

This command allows you to query or set your current filename which is used 
by the EDIT (e), READ (r), WRITE (w) and EXECUTE (x) commands when you 

omit their filename. 

The first form of this command displays your current filename on the command 
line and waits for you to clear it by typing the carriage return key. 

The second form sets the current filename to be the filename specified. 

The FILE command must be the last command on a line. 

Current Line: 

Not affected. 

Condition Register: 

Not affected. 
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416 g - Global 

Syntax: 

dine range>g/<pattem>/<more editor commands> 
cline range>g A /cpattem>/cmore editor commands> 

Description: 

The GLOBAL command checks each line in the indicated line range for the 

presence of the indicated cpattemx The first form marks lines which contain the 
pattern while the second form marks lines which DO NOT contain the cpattemx 
The GLOBAL command then executes the following commands for each marked 
line, with the current line set at the marked line before executing. If no line range 
is specified then ALL lines are searched for the cpattemx For example: 


g/ A Comment/d 

would remove all lines containing the string "Comment" at the beginning of the 
line. To print them before deleting use: 

g/ A Comment/pd 

To Change all occurrences of the string "minimum" to "maximum" and print the 
changed lines, issue a: 

g/minimum/s//maximum/p 

To delete all lines which don’t end in the string ",c" issue a: 
g A A.c$/d 

To append the line "--" after each line in the buffer, issue a: 

g/ A /a - 

To reverse the order of lines in your buffer, issue a: 
g/ A /.mO 

Finally, to print the lines around each line containing the string "function", issue a: 
g/function/.-5,.+5p 
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Current Line: 

When the GLOBAL command is finished, the current line has the value it 
had after the last command executed during the GLOBAL operation. 

Condition Register: 

When the GLOBAL command is finished, the condition register has the value 
it had after the last command executed during the GLOBAL operation. 
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4.17 i - Insert Before Current Line 

Syntax: 

<line>i 

<line>i <text> , : 

<line>id 

Description: 

The first two forms of this command turn ON option newline (n+) and open 
up a new line before the current line. If the second form with <text> is specified 
then that text will be placed at the start of the newly opened line. This form is 
often used within a GLOBAL (g) command to append a string before a set of mat¬ 
ched lines. The blank between the T and <text> is required. 

The third form inserts the last deleted line (or range of lines) from the delete buf¬ 
fer. Option newline is not affected. 

The insert command must be the last command on a line. 

Current Line: 

Set to the address of the new line opened up. 

Condition Register: 

Not affected. 
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4.18 j - Join Two Lines 
Syntax: 

<line>j 

This command joins the indicated line to the line following it. As an intere¬ 
sting example: 

uflj 

will attempt to join all lines in the file. 

Current Line: 

Set to <line>. 

Condition Register* 

tSf 

Set if a join occurs. Will always be FALSE on last line. 
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4.19 k - Kopy Lines 

Syntax: 


dine range>k<target lino 

Description: 

This command kopies the indicated range of lines to the line following the 
specified ctarget lino. The ctarget line> may be zero to insert before line one but 
the ctarget line> may NOT fall within the source cline range>. The source lines 
specified by cline range> are left untouched in the buffer. 

The ’k’ for copy was chosen since the letter ’c’ was already in use by the Line 
Editor and it was felt that its function should be maintained in the Screen Editor for 
consistency. It’s not that we kan’t spell. 

Current Line: 

Set to the first of the kopied lines. 

Condition Register: 

Not affected. 
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4.20 1 - Learn 



1 <character> 

Description: 

All input until a Ctrl-Break will be saved as a macro. From this point, each 
occurrence of <character> will be replaced by the learned input stream. To leam a 
key sequence for the FI key you would enter: 

1 \81 


Current Line: 

Not affected 

Not affected 
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4.21 m-Move Lines 

Syntax: 

<line range>m<target lino 


Description: 

This command moves the indicated range of lines from their current position 
in the buffer to just after the specified ctarget line>. The ctarget hne> may be zero 
to insert before line one but may not fall within the source <line rangex 


Current Line: 


Set to the first of the moved lines. 


Condition Register: 


Not affected. 
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4.22 o - Option Query/Set 

Syntax: 


ocoption characterxoption modifier 
where: <option character is a single letter 

^ ..r. {a,b,c,d,e,f,i,j,l,m,n,s,t,w}. 

coption modifier> is a V, 0 r ’?’ 

Description: 


The OPTION command allows you to change or query your editing ontinnc 
The option selected is specified by the <option character and the operation is 

£S th£ i <?P? on modifier. A V will turn an option ON a P ’-’ will turn an 
option OFF and a ~ will cause the option to toggle. A does not affect the 

SZiS t‘S'm? v' 1 " re ie' r 7 RUE 7*' «*» <*. ON »d??LsE if 

P e + ’ and ~ do not affect the condition register. 

Current Line: 


Not affected. 

Condition Register: 

Set TRUE or FALSE if coption modifier is a 
Each option is briefly described in a subsection below. 

4.2X1 oa - Option Anchor 


Whenever a pattern search is made, the editor will leave your cursor at the start 

’ WnT — ° f the pattem matched * Should vou specify a search for the string 
mouse with a+ your cursor will be anchored to the’m’ in mouse With (a ) thp g 

charaar, 0 atL the°’e‘; 0ned ^ CharaCter after * e matched strin 8 "mouse''(the 

4 * 22.2 oh - Option Blank 


iiHililsssssr 


ED62 



4.22.3 oc - Option Command 

This option indicates whether your active cursor is in the command area (e+) or 
text area (c-). It is often queried and set within macros. The FI, F2 and large 
PLUS key are examples of macros which do this. 

4.22.4 od - Option Dual 

This option, like option anchor (oa) concerns pattern matching. If OFF (d-) then a 
search for "mouse" would match the string "MOUSE", "MoUse", MOUsE and so 
on in your text. With (d-f) the pattern matcher differentiates between upper and 
lower case. 

4.22.5 oe - Option Environment 

This option is handled quite differently from the other options. It does not have an 
ON or OFF state. Each time you specify an oe-f command, your current options 
will be saved. They may be restored by an oe- command. The editor only main¬ 
tains a single level of environment stacking. Multiple oe-f- commands simply 
overwrite previous saves and multiple oe- commands simple restore the last en¬ 
vironment saved by an oe-f. This command is useful within macros where it may 
be necessary to temporarily change an option to perform a required function. Only 
the current state (ON/OFF) off each option is saved. 

4.22.6 of - Option Fill 

This option when ON (f+) will cause automatic filling of input lines at your 
defined right margin. The default right margin is column 60. Should you attempt to 
enter a character in this column, then any preceding characters of a word will be 
moved to the next line. Using this option you may enter text without having to type 
a carriage return to end each line. This is extremely useful when entering documen¬ 
tation and letters. 

4.22.7 oi - Option Insert 

With (i-f), all characters typed will be inserted before the cursor. 

4.22.8 oj - Option Justify 

With (j+), all filled lines will also be justified at your right margin. 
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4.22.9 ol - Option Limit 

This option will flash (1+) when a limited tag has been set. 

4.22.10 om - Option Meta Characters 

With (m+), meta characters are enabled during pattern matching. The meta charac¬ 
ters "@$ A &*[." are explained in detail on the section describing the pattern mat¬ 
cher. 

4.22.11 on - Option Newline 

Whenever a carriage return is entered in the text area while this option is ON (n+), 
a new line will open up after your current line to allow you to type in new text. 

This can be thought of as line insert mode and is similar to character insert mode 

(oi). 

4.22.12 os - Option Autosave 

With (s+), your buffer will be automatically saved in the file "autosave" after every 
20 lines of input. While writing to the disk you may still continue to type up to 
256 characters per line, however, your keys will not be echoed until the write is 
complete. 

4.22.13 ot - Option Tabs 

This option is similar to option blank (b). Tab characters in your text are expanded 
into enough spaces to reach the next tab stop. What may appear as 4 spaces may 
only be one ’real’ character. Turning this option ON (t+) will display the actual 
tab character as a right triangle. With (b+) also on, the spaces which pad the tab to 
the next tab stop will be displayed as centered dots since they do not exist within 
the buffer. Tabs are characters which are heavily used within C programs for 
indentation. 

4.22.14 ow - Option Wrap 

With (w+) pattern searches will wrap around from top to bottom or bottom to top 
in your buffer. 
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4.23 p - Print Lines 

Syntax: 

<line range>p 
dine range>P 

Description: 

This command clears your screen and prints the specified lines on your 
screen. If the number of lines exceeds the size of your screen, the command will 
pause until you type a character to continue. If the first form is used (small p), then 
any non-printing characters (less than hex 20 and greater or equal to hex 80) will 
be expanded into a^ sequence. This can be useful in finding out the hex values 
of some of the Function and Cursor keys (proceed them with the on the keypad 
to put them in your text). This command is nearly always used in conjunction with 
the GLOBAL command. It allows you to display lines which are not adjacent in 
your buffer. For example: 

g/index/p 

will print all lines on your screen that contain the string "index". You may not edit 
the displayed lines using the cursor keys. The editor has temporarily dropped out 
of full screen mode. 

Current Line: 

Set to the last line printed. 

Condition Register: 

Not affected. 
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4.24 q - Quit (Leave the Editor) 

Syntax: 

q 

qq 


Th * s , command terminates the current editing session. For your protection the 
editor will not let you quit via a single ’q’ if your buffer has been modified since 

f n m a w m n°n SaV t ed Y °^ Can f ? rce a quit without saving by using the second 

within^GLOBAL tote™ nS ^^ C ° mmand ° naHne3ndmuStn0tbe 

Current Line: 


Not affected. 

Condition Register: 

Not affected. 
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<line>r 

<line>r <filename> 



This command reads in the contents of a file and appends it immediately 
following the line <line>. If a <filename> is not given, the current file is used. If 
<line> is omitted, it will append the file after the current line. 

The READ command must be the last command on a line. 

The READ command can not be used inside a GLOBAL (g) or UNTIL (u) com¬ 
mand. 

Current Line: 

Set to the address of the first line read from the file. 

Condition Register: 

Not affected. 



4.26 s - Substitute Text 



dine range>s<dl><pattem><dlxreplacement textxdl> 

cline range>scnumberxdlxpattemxdlxreplacement textxdl> 

Description • 

This command replaces occurrences of cpattem> with the string emplace¬ 
ment text> in the line range specified. If no line address is specified, substitutions 
are made on the current line. The pattern and replacement text are delimited by a 
single character cdl>. It is general practice to use the T character for this purpose, 
however, any other character not appearing in cpattem> or creplacement text> 
may be used instead. 

The first form replaces ALL occurrences of the given pattern on a line while the 
second form only replaces the cnumber>th occurrence on the line. 

The character has a special meaning (with option m+) when used in the re¬ 
placement text. It will be replaced by the text of the pattern matched. For example: 

s/however/&,/ 

is equivalent to: 

s/however/however,/ 


This can be extremely useful when matching complex patterns where you may not 
know the exact text matched. The is NOT a special character in <pattem>, and 
all the pattern matching meta characters are not special in emplacement text>. 

The backslash V character may be used in the definition of <pattem> and cre¬ 
placement text> to escape the meta characters, and the delimiter character <dl> 
so they lose their special meaning. For example: 

s/myfile\*/Vyourflle\&/ 

will replace the string "myfile*" with 7yourfile&". You can also match and re¬ 
place your text with exact hexadecimal character values using a\hh sequence. One 
common use is splitting a line by inserting a record separator character. The com¬ 
mand: 
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s/and further more/&\!e/ 

W ill split the current line after the string "and further more". You can notmatch a 
record separator character in you text buffer as they are not actually stored, but 
stripped and added when you read and write your buffer to a file. 

The substitute command is often used for making QNX command (ec) files. You 
first create a file of pathnames using the "files" command. 

files p=*.c -v >fiist - create a list of my C programs 

You would then edit the file "flist" and perform the following substitutions to 
create a command file to encrypt all your C programs. 

*s/ A .*$/<&>&/ - duplicate names with redirection 

*s/..$/.e/ - replace last .c with .e 

*s/ A /crypt / - prefix the crypt command in front of 

all filenames 

You would now write the file, leave the editor and execute the file, 
sh flist 

The @™ construct can be used to turn runs of spaces into tabs 

s/@(t)A01/ - mark tab stops with a Ctrl-a 

s/ *\01/\09/ - replace runs of spaces ending 

on a tab stop with a TAB 


Current Line: 

Set to the address of the last line of the specified range. 

Condition Register: 

Set TRUE if a successful substitution takes place, otherwise, it is set FALSE. 
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4.27 t - Translate a Key on Input 

Syntax: 


t <character> <replacement text> 
t <character> 
t ? <character> 

T <character> replacement text> 
T <character> 

T ? <character> 

Description: 


This command translates an input character into a string of characters. It is 
possible™ 311 ' 1 whlch makes the macro definition of the function and cursor keys 


TJe first form translates the indicated character <charactei> into the string of 
characters emplacement text> whenever that character is typed. The second form 
removes any translation m effect. 

The third form will display the current translation of the indicated character on the 
command line allowing you to modify it if desired. 

TJe definition of <character> may be a '>hh sequence. If you wish to enter the 
character to be translated directly (you may not know its hexadecimal value) you 
should precede the character with the key on the numeric keypad. This suppre- 
sses any translation currently in effect for the key. It is recommended that you 
NOT translate the or V key. You should keep in mind that one level of backs¬ 
lash escapes is stopped off during the translate command. This unfortunately 
means that if you wanted to match a backslash in a substitute command, you would 
have to type four of them to get one. 


t \84 \ffsA\\V?Ale 
\ffsAV?Ale 


You enter this 
This would be saved for the 
definition of F4. The 
SUBSTITUTE command would 
turn the \\ into a single \ 
when the macro was executed. 


If you use the little Y command then-recursive definitions are allowed If 
a capital 1 then a macro within a macro will not be expanded. 


you use 
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The special character \ff (see section on special characters) should be prefixed to 

any translation that you wish executed as a command. It causes all characters up to 
the next record separator Me to be collected (no echo) in a hidden buffer and then 
executed as a command. Any current text on the command line is NOT affected. 

This allows you to define command translations which are independent of where 

your active cursor is. For example: 

t \01 MT/procedureAle 

would cause a Ctrl-a to be translated into a scan for the pattern /procedure/. Note 
that the Me was necessary to force execution. Without it you would have to type 
the carriage return key yourself at the keyboard. If we were to omit the \ff, then 
the text would be entered at the active cursor which would probably be ok if you 
were on the command line, but unpleasant if you were in the text area. 

As a further example, to translate the FI key into the string "QNX Software 

Systems" you would enter the command: 

t \S1 QNX Software Systems 

Note that we did not prefix the replacement text with a \ff, nor did we end it with a 

Me. Anytime you now type an FI, the string "QNX Software Systems" will be 
entered at the active cursor, exactly as if you had typed the characters on the key¬ 
board yourself. 

Current Line: 

Not affected. 

Condition Register: 

Not affected. 
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4.28 u - Until 

Syntax: 

dine range>u<count> cmore editor commands> 
cline range>u<condition> cmore editor commands> 
cline range>u<count><condition> cmore editor commands> 
cline range>u cmore editor commands> 

where ccondition> is: t - TRUE 

f - FALSE 

Description: 

This command is used to repeat a list of commands a number of times until a 
given condition is satisfied. The list of commands may contain another UNTIL if 
desired, however, it may NOT contain a BRANCH (b) command. The space be¬ 
tween the ccount> or ccondition> and cmore editor commands> is required. 

The first form will repeat the list of commands ccounO times. 

The second form will set the condition register to the opposite of ccondition> and 
repeat the entire list of commands until the condition register matches ccondition> 
AT THE END OF one of the repetitions of the command list. 

The third form will set the condition register as in the second form but will repeat 
the list until either ccount> is reached, or the condition register matches ccon- 
dition>, whichever occurs first. 

The final form will repeat forever, or until you type break (or an error occurs). 

In all cases the UNTIL will terminate immediately if any command in the list 
generates an error. In this case the condition register will be in the state it had 
before the error. The ERROR will NOT be printed, but absorbed by the UNTIL 
command. This allows you to prevent a command from issuing an error message 
by preceding it with a "ul ". For example: 

ul s/IBM/I.B.M/ 

will not generate an error if the substitute fails. 

If both ccount> and ccondition> are omitted, then the UNTIL will repeat until an 
error occurs or you type Ctrl-Break. 
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Current Line: 

When the UNTIL command is finished, the current line will have the value it 
had after the last command executed during the UNTIL operation. 

Condition Register: 

When the UNTIL command is fmished, the condition register will have the 
value it had after the last command executed during the UNTIL operation. 
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4.29 v - View Screen Options 
Syntax: 

va<number> <number> <number> 
vc 

vc<number> 

vf 

vl<quantity> 

vr<quantity> 

vs<quantity> 

vt214!8 

vz 

vznumber 

Description: 

This command allows you to change some of the parameters associated with 
your screen. The parameter is specified by the character following the VIEW (v) 
command. The condition register is not affected by this command. 

Current Line: 

Not affected. 

Condition Register: 

Not affected. 

Each parameter is briefly described in a subsection below. 

4.29.1 va - Attribute 

This command allows you to change the attributes (colour) of the three regions of 
your display. The first number must lie between 1 and 3 and indicates the region. 

1 - Status line 2 - Command line 3 - Text lines 

The second and third number select the foreground and background colour. 

0 - Black 1 - Blue 2 - Green 3 - Cyan 

4 - Red 5 - Magenta 6 - Yellow 7 - White 
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Hie foreground colour will be intensified if values greater than 7 are used. 

8 - Black 9 - Blue 10 - Green 11 - Cyan 

12 - Red 13 - Magenta 14 - Yellow 15 - White 

This command is ignored when used with the monochrome display. Users with a 
colour display may wish to add this command to the end of the file 
Vcmds/ed.macros ’. 

4.29.2 vc - Center Line 

When used without an argument (form 1 above) this causes your screen to be 
redrawn with the line your cursor is on positioned at your defined center line. You 
may redefine your center line by specifying a number (second form above) be¬ 
tween 1 and 23. The default macro file sets your center line at 3. 

4.29.3 vf - Full Display of Text and Attributes 

The editor keeps track of the attributes stored on each line. To increase the speed 
of screen updates on the console, Ed will not update the attributes when it believes 
they have not changed. Programs such as QSPELL which modify the screen at¬ 
tributes without the editors knowledge may result in permanent attributes which Ed 
will not remove. The view full command will force Ed to always update the at¬ 
tributes as well as the text on your screen. 

4.29.4 vl - Left Margin 

This command defines your left margin. The term <quantity> may be a simple 
number in which case your margin will be set to that value, or it may be a number 
preceded by a V or in which case that value will be added or subtracted from 
the current value. This lets you define absolute or relative changes to your mar¬ 
gin. For example: 

vl+5 

will increase your left margin by five and: 

vlS 

will define your left margin to be five. As a special case, a V will set your margin 
to the column that your text cursor is currently on. 
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Your left margin defines the point you will return to in your text whenever you 
type a carriage return. The characters before your margin will be filled by blanks 
unless you have changed your default fill character (see ZAP (z) command). 

Your left margin is constrained to lie between 1 and your right margin. 

4.29.5 vr - Right Margin 

This command defines your right margin in the same manner as "vl" defined your 
left margin. Your right margin defines the point at which filling (automatic 
generation of a carriage return) will occur on text entry if you have option fill ON 

(f+). 

Your right margin is constrained to lie between your left margin and column 1000. 

4.29.6 vs - Scroll Screen 

This command causes your screen to be scrolled. If you specify a negative quan¬ 
tity then the scroll will be backward and if you specify a positive quantity then the 
scroll will be forward. This command always causes an immediate refresh of your 
screen. This allows you to look at snap shots of your screen during the execution 
of an until (or any list of commands). The command: 

u20's/*/+/ 

would only display the final version of the line you modified when the editor 
finished execution. The command: 

u20 s/ A /+/vsO 

would give you a snap shot after each iteration of the substitute command. 

4.29.7 vt - Set tab settings 

You may set your tab stops at every 2,4 or 8 characters on the screen. The default 
is 4. 

4.29.8 vz - Zoom the size of your screen 

When given without arguments this command will switch to the next hardware 
supported screen size. If the number is given it will switch to 

vzO - Size of screen upon entry. 

vzl - Screen size 1 (25 by 80 on an EGA). 

vz2 - Screen size 2 (43 by 80 on an EGA). 
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vzX Hardware dependent. 



4.30 w - Write Buffer to a File 

Syntax: 

<line range>w 

<line range>w <filename> 

<line rangowa 

<line range>wa <filename> 

Description: 

This command writes out the specified lines to a file. If a <filename> is not 
given the current file is used. If the dine range> is omitted then ALL lines are 
written. 

The last two forms (wa) will append the specified lines to the end of the file. 

If a <filename> is specified and the current filename is not defined, then the 
specified <filename> will become the current filename. Note that <filename> can 
of course be a device like 5 $ipt\ 

Current Line: 

Set to the address of the first line written. 

Condition Register: 

Not affected. 
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x <filename> 

Description: 

This command will open up a file and execute its contents as a series of 
editor commands. If a <filename> is not given the current file is used. 

This command is commonly used to load macros via a file of translates. The editor 
does an EXECUTE on the file "/cmds/ed.macros H immediately after execution 

begins. An execute file may NOT contain another execute. 

The EXECUTE command can not be used inside a GLOBAL (g) or UNTIL (u) 
command. 

Current Line: 

The current line is set by the commands in the execute file. 

Condition Register: 


The condition register is set by the commands in the execute file. 



4.32 y - Yut? 

Syntax: 

dine range>y"<prompt text>"<command chars> M <arguments> 



This command does not know what it is. It will print cprompt text> on the 
command line then wait for you to type the letter of a command. If the character 
you type matches the nth character of ccommand chars> then control will transfer 
to the nth line. Each line is separated with a record separator (\1E). 

y"k for kopy or m for move f, km f, \le\ff#k.b2\le\ff#m.\le 

would prompt: 

k for kopy or m for move 

on the command line and pause for you to type a character. If you typed an’m’ 
then the command: 

#m. 

would be executed, which happens to be a tagged move to the current line. 

If the typed character is not found, then the last command will be executed. The ’n’ 
command is an invalid command and can be used to generate errors on invalid 
keys. In the following example, a space or any invalid key will generate an error: 

y ,f k for kopy or m for move”km ,, \le\ff#k.b3\le\ff#m.b2\le\ffn\le 

Current Line: 

Set according to the command executed. 

Condition Register: 

Set according to the command executed. 
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4.33 z - Zap 
Syntax: 

dine range>zccccharacter> 

cline range>zcd 

cline range>zcDclocation> 

cline range>zceclocation> 

cline range>zcfccharacter> 

cline range>zchclocation> 

cline range>zcl 

cline range>zcp 

cline range>zcr 

cline range>zcRcnumber> 

cline range>zcs 

cline range>zh 

cline range>zkcline> 

cline range>zlc 

cline range>zld 

cline range>zle 

cline range>zlf 

cline range>zlj 

cline rangozlo 

cline range>zlp 

cline range>zlq 

cline range>zlr 

cline range>zlR 

cline range>zlR"filename" 

cline range>zls 

cline range>zlt 

cline range>zlu 

cline range>zlw 

cline range>zlw"filename" 

cline range>zmctext> 

cline range>zp 

cline range>zq# 

cline range>zq! 

cline range>zvcdigit> 

Description: 

This command consists of a number of useful subcommands which relate 
directly to the capabilities of a full screen editor. The subgroup starting with ’zc’ 
(ZAP CURSOR) deal with the cursor and are further subdivided by a third 
character to indicate a particular function. The cline range> for the "zc" group 


ED 81 



may be a single line address of zero in which case the command will be applied to 
the command line instead of the text area. Each ZAP function is described in a 
subsection below. 

Current Line: 

In all cases, it is set to the last line of the specified range, however, not all 
ZAP commands use the line range information (zp for example). 

4.33.1 zee - Zap Cursor Change 

This function changes the character under the cursor to the character specified. 

The <character> may NOT be a \hh escape sequence but may be a carriage return. 

If option insert is ON (i+) then <character> is inserted BEFORE the cursor. 

Condition Register: 

Not affected. 

d.H.7 wd - Zar> Cursor Delete 

This function deletes the character under the cursor causing the rest of the line to 
shift to the left. 

Condition Register: 

Trying to delete a non-existent character (you are to the right of the end of the 
line) will set the condition register FALSE. A successful delete sets it TRUE. 

4.33.3 zcD - Zap Cursor Delete Multiple 

This function will delete all characters from the current cursor position to the posi¬ 
tion specified by <location>. The <location> is specified in the same manner as the 
’zch’ command. 

Condition Register: 

Trying to delete a non-existent character (you are to the right of the end of the 
line) will set the condition register FALSE. A successful delete sets it TRUE. 

4.33.4 zee - Zap Cursor Erase 

This function will erase all characters from the current cursor position to the posi¬ 
tion specified by clocationx This allows erase to end of field (right margin) to be 
implemented via a 
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zcer 


The <location> is specified in the same manner as the ’zch’ command. If the field 
does not end the line, the field is replaced with blanks instead of being deleted. 
This preserves column integrity. 

Condition Register: 

Set TRUE if any characters are erased. 

4.33.5 zcf - Zap Cursor Fill 

This function defines the fill character to be used whenever you type a character to 
the right of your text (indicated by a small centered dot in option blank (b+)). The 
default is to extend the line with blanks. However it may be changed to any 
character, a period being a typical example. The <character> may NOT be a\hh 
escape sequence. 

The fill character is often changed to a TAB when used in conjunction with the 
Ctrl-b (begin indent) and Ctrl-e (end indent) keys when writing programs. Inden¬ 
ting by TABS rather than spaces is strongly recommended. 



NOT affected. 


4.33.6 zch - Zap Cursor Horizontal 

This function moves the cursor horizontally on the line. The movement may be 
absolute, relative or based upon a pattern. The field <location> determines the 
type of movement and can be one of: 


<number> 

+<number> 

-<eumber> 

$ 

1 

r 

/pattern/ 


Absolute movement to indicated character cnumberx 
Relative movement forward <number> characters. 
Relative movement backward <number> characters. 
Move to end of line. 

Move to left margin. 

Move to right margin. 

Starting at the current cursor attempt to match 
the indicated pattern. Note that the line is 
assumed to start at the cursor and all characters 
to the left of the cursor are ignored. The 
pattern / A ./ would match the character at the 
cursor NOT the beginning of the line. Option 
anchor will determine the new location of the 
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cursor on a match. 

?pattern? Starting at the current cursor and scanning 

BACKWARDS, attempt to match the indicated pattern. 

Note that the line is assumed to start at the 
cursor and extend backwards to the beginning of 
the line. All characters to the right of the 
cursor are ignored. Due to the backward scan, the 
line will appear reversed to the pattern. To 
match the string "IBM" you would specify the 
pattern ?MBI?. This is only true of backward 
searches using the ZCH command. 

In all cases above, the cursor is limited to lie between index 1 and 512. 

Condition Register: 

An attempt to move the cursor outside the text on the line (or a pattern match 
fail) will set the condition register FALSE, otherwise, it is set TRUE. 

4.33.7 zcl - Zap Cursor Lock 

When the editor is forced to move the cursor to a line which is not within the cur¬ 
rently displayed screen, it will by default redisplay with the cursor line positioned 
at your defined center line (see vc<number>). The Zap Cursor Lock command, 
LOCKS the cursor to the TOP or BOTTOM of the screen on a redisplay. Concep¬ 
tually, if your cursor must move off the top of your screen then, it will remain 
locked at that position and your text will scroll down as required. Likewise, if your 
cursor must move off the bottom of your screen, then it will remain locked at that 
position and your text will scroll up as required. 

As an example the UP ARROW and DOWN ARROW are implemented as: 

.-ljzcl and .+l|zcl 

to prevent a re-centering of your display when your cursor attempts to leave the 
screen. 

Condition Register: 

NOT affected. 
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4.33.8 zcp - Zap Cursor Purge 

This command purges all characters in the character delete buffer. 

Condition Register: 

NOT affected. 

4.33.9 zcr - Zap Cursor Restore 

This command causes the last character put in the delete buffer to be restored at the 
current cursor position. If option insert is ON (i+) the character will be inserted 
before the cursor. 



Set TRUE if the character delete buffer contains at least one character to 
restore. 

4.33.10 zcR - Zap Cursor Restore Multiple 

This command will restore the last <number> characters put in the delete buffer at 
the current cursor position. If option insert is ON (o+) the characters will be in¬ 
serted before the cursor. 

Condition Register: 

NOT affected. 

4.33.11 zcs - Zap Cursor Save 

If the cursor is positioned on a character, then it is saved in the character delete 
buffer. If the cursor is not on a character (off to the right of the line) then nothing 
is saved. 

The character delete buffer may hold a maximum of 256 characters. Saving more 
than this number causes any new character to be inserted at the front and the oldest 
character is lost. Only the last 256 characters are kept. 



Set TRUE if a character is saved. 
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4.33.12 zh - Zap Home 

This command will move your cursor to the top left hand comer of a tagged block 
of text. For example, say you wish to write a macro which saves a tagged block of 
text to a file, executes the SORT command and replaces the tagged tagged text 
when sorted. It is necessary to ensure that the cursor is positioned at the top left 
comer of the text when you read the file back in. 

t\01 \ffzh\le\ffzp#zlw u tmp M ! Isort tmp +r\le\ffzpzlR M tmp'\le 


Condition Register: 

NOT affected. 

4.33.13 zk - Zap Kopy 

This command provides a convenient method of kopying a text line to the com¬ 
mand line and vise versa. A line address of zero designates the command line. For 
example 

Ozk. - kopy command line to current line 

.zkO ■ kopy current line to command line 

Condition Register: 

Not affected. 

4.33.14 zlc - Zap Line Center 

This command will center the text between the left and right margins of the in¬ 
dicated lines. 

Condition Register: 

NOT affected. 

4.33.15 zld - Zap Line Delete 

This command will delete the text between the left and right margins of the in¬ 
dicated lines. 
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Condition Register: 

NOT affected. 

4.33.16 zle - Zap Line Erase 

This command will erase the text between the left and right margins of the in¬ 
dicated lines. 

Condition Register: 

NOT affected. 

4.33.17 zlf-Zap Line Fill 

This command will fill the text between the left and right margins of the indicated 
lines. 

Condition Register: 

NOT affected. 

4.33.18 zlj - Zap Line Join 

This command will set the join flag on the indicated lines. 

Condition Register: 

NOT affected. 

4.33.19 zlo - Zap Line Overstrike 

This command will set the overstrike flag on the indicated lines. 

Condition Register: 

NOT affected. 

4.33.20 zip - Zap Line Paragraph 

This command will set the paragraph flag on the indicated lines. 
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Condition Register: 

' NOT affected. 

4.33.21 zlq - Zap Line Query 

This command will set the condition code true if there are any marks set. 

Condition Register: 

TRUE if any marks set. 

4.33.22 zlr - Zap Line Restore 

This command will restore the contents of the delete buffer where the current text 
cursor is. The delete buffer is not affected. 

Condition Register: 

NOT affected. 

4.33.23 zlR - Zap Line Restore File 

This command will read the contents of a file into the delete buffer then restore the 
contents of the delete buffer where the current text cursor is. If no file name is 
specified, then the file Vtmp/group.member’ will be used where group and member 
are numbers. 

Condition Register: 

NOT affected. 

4.33.24 zls - Zap Line Save 

This command will save the text between the left and right limit at the end of the 
delete buffer. Limits are set by tags. 

Condition Register: 

NOT affected. 
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4.33.25 zlt - Zap Line Tag 

This command TAGS the indicated line if it was untagged and UNTAGS it if it 
was TAGGED. If there are already two tags in effect then this tag will replace one 
of the tags. NOTE: If two ’zlt’s occur within 1/2 second then option limit will be 
enabled and the line will not be untagged. 

Condition Register: 

NOT affected. 

4.33.26 zlu - Zap Line Untag 

This command removes all tags in the file if any are set or sets the last tags if there 
are not any tags set. It is a toggle. 

Condition Register: 

NOT affected. 

4.33.27 zlw - Zap Line Write 

This command will save the text between the left and right limit at the end of the 
delete buffer. Limits are set by tags. The data is then saved into a file. If no file 
name is specified, then the file Vtmp/group.member’ will be used where group and 
member are numbers. 

Condition Register: 

NOT affected. 

4.33.28 zm - Zap Message 

This command will print the message which follows on the command line. This is 
useful as a prompt. 

Condition Register: 

NOT affected. 

4.33.29 zp - Zap Purge 

This command purges all lines in the line delete buffer. 
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Condition Register: 

NOT affected. 

4.33.30 zq - Zap Query 

This command sets the condition code based upon the character which follows the 

zq. 

Condition Register: 

# - TRUE if any tags have been set 
! - TRUE if zero exit status of last command 

4.33.31 zv - Zap Version 

This command sets the condition code based upon the version number of the 
editor. The version is a number between 0 and 9. If the editors version is greater 
than or equal to the digit specified the condition code will be set TRUE. 

zvl Set condition code TRUE if editor version 1 or later 


Condition Register: 

TRUE if editor is greater than or equal to indicated version. 


ED 90 




This section is intended for the advanced user who wishes to add functions to the 
supplied macro file "/cmds/ed.macros" or define a set of new macros for a par¬ 
ticular editing task at hand. Before trying your hand at new macros you should 
have read both the Tutorial Guide and Reference Manual in detail. Macros are 
basically very simple to write, BUT only if you have a good grasp of the many 
editor commands described in the reference manual. 

5.1 What is a Macro 

A macro is just the simple replacement of an input key with a string of characters. 
The replacement string contains the keys you would have to type to perform the 
required function manually. As an example, let’s look at the definition of the Ins 
key. Each time it is typed, it toggles option character insert (oi). You could per¬ 
form this task manually by going to the command line and typing the command 

or* 


which will toggle the option. You would then want to go back to the text area if 
that’s where you came from. If you were already on the command line with a 
partially typed command then the situation is slightly more complex. You can’t 
type in a new command on the command line without deleting what is currently 
there. To overcome this difficulty, the editor provides a very special character 
called the ccommand char> which causes all input following it, up to the next 
newline to be collected (without echo) in a hidden command buffer which is then 
executed. By prefixing all commands with this character you can execute com¬ 
mands regardless of whether you are on the command line or in the text area. The 
value of die command character is hexadecimal FF and may be entered directly 
from your key board by holding down the Alt key and typing the backarrow key 
normally used for character delete. You can now toggle insert mode at ANY time 
by typing the string 

ccommand char>oib<new!ine> 

where ccommand char> is an Alt-backarrow and <newline> is either a carriage 
return or a record separator (Ctrl A ). To turn this into a macro for the Ins key you 
would translate the value generated by the Ins key into the above string. 



Newline character. 

Command character. 

Hexadecimal value generated by 
the Ins key. 
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If you leave off the command char then the string 


or* 


followed by a newline would be entered at the active cursor. Likewise, if you 

leave off the newline, then the command will be collected, but you will have to 
supply the newline yourself by typing a carriage return. 

Most macros are this simple. However, care should always be taken to ensure 
reasonable behavior when a requested operation may fail. An example of this is 
the down arrow key on the keypad. It is designed to move you down one line. 

This could be performed by executing the command 

.+1 

which works fine until you try to move past the last line in your buffer where you 
will be greeted by an unpleasant error message which will quickly annoy any user. 
The simple solution is to limit the line address to remain within the buffer using the 

T operator. The resulting macro definition would be: 

\ff.+l|\le 

which behaves in a friendlier fashion. As one final point, to prevent your screen 
from being re-centered when you attempt to leave the screen, you might add a ZAP 
CURSOR LOCK command resulting in 

\ff.+l|zcl\le 

Lets look at one more simple example illustrating the importance of planning your 
macro’s behavior in all possible situations. You want the PgDn key to display the 
next page of your buffer. Your text area is 23 lines so you might simply attempt to 
move forward 23 lines via a 

.+23 

This has two problems 

1. You may not have another 23 lines in the buffer. 

2. If your current line was not on line 1, then you would miss part of the next 
page. You should be jumping forward relative to the address of the top line of 
the current screen. The PgDn is currently defined as 
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t \aa \ff@+23I \le 


Limit address to lie within buffer 
Address of top line on the screen. 
Hexadecimal value generated by the 

PgDn key. 


5.2 Multi-line Macros 

Most of your macros will consist of one or more editor commands entered as a 
string which makes up a single command line. There are cases, however, where 
you will find that you need to enter a multi-line command. You may do this by 
simply embedding <newline> characters in your translate string. The macro 


t \84 \fful *s/register//\le 


\fful *s/short/int/\le 
Start of line two. 
End of line one. 
Start of line one. 
Hexadecimal value 
generated by F4 key. 


defines a macro which will remove all occurrences of the string "register" and 
change all occurrences of the string "short" to the string "int". The UNTIL one 
(ul) will prevent an error from being printed if the substitute fails to find a match. 
By placing them on two lines we are guaranteed to perform the second substitute 
even if the first one fails. Remember, an error (even inside an UNTIL) terminates 
execution of the current line. 

5.3 Macros Containing Branches 

The most common use of multi-line macros involves the BRANCH (b) command. 
This command was included in the editor to allow you to perform conditional 
execution of editor commands within macros. A simple example is the large 
PLUS key on your keypad which performs one of two tasks. If you are in the text 
area it simply places you on the command line. If, however, you are already on the 
command line, it simulates your entering a carriage return to execute any com¬ 
mand, then places you back on the command line. Hitting carriage return would 
normally execute any command then put you back in the text area. 
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This key is defined as. 


t \§7 \ffoc?b2f\le\ 



1 © 

Return to command mode. 
Literal newline to execute 

command line. 

Query and set condition 

register if on command line. 
Hexadecimal value generated 
by the large PLUS key. 


This macro is interesting for two reasons. 

1. It makes use of the BRANCH (b) command to conditionally execute editor 
commands. If you are in the text area it will skip two <newline> characters 
and only execute the "\ffoc+\le" which will place you in command mode. 

2. It mixes literal text (which is entered at the current cursor) with command text 
(which is preceded by a\ff and is collected in an execute buffer). If you were 
already on the command line it will not branch, and therefore enter a <new- 
line> on the command line which will cause it to be executed. You will then 
fall into the code which sets option command and goes to the command line. 

Defining complex macros which contain several branches and several lines quickly 
becomes confusing when displayed as a single line with embedded <newline> 
character escapes. The macro for the F2 key illustrates this. 

t \82 \ffon?b3t\le\ffi\le\ffb4\le\ffon-zchl\le\ffb2t\le\ffd\le 


This macro can be better understood when displayed as the multi-line sequence 


t \82 \ffon?b3t 

\ffi 

\ffb4 

\ffon-zchl 

\ffb2t 

\fffd 


Check if option newline is on or off. 

If it is off, then do an insert command 
and skip the rest of the macro. 

Else go to the beginning of the line and skip 
to the end of the macro if line isn’t empty. 
Delete the empty line. 


It should be remembered that the zap cursor horizontal command (zch) will set the 
condition register false if you move to a position which does not contain a charac¬ 
ter. If there is no character in the first column then the line must be empty. 


There is a macro which will allow you to type in a macro in your text buffer in the 
multi-line form above and convert it into a single string on the command line 
which you may type carriage return to enter. This macro is defined in your 
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"/cmds/ed.macros" file, but has been commented out by a double quote. You may 
remove this quote and then execute the file 

x /cmds/ed.macros 

to define this macro as your Alt-m key. If you type the Alt-m key in the text area, 
it will compress your buffer into a single line and move it to the command line for 
execution. If you are on the command line, then it will take a macro which you 
have displayed via the 

I ? \fafa 

command and place it in your text buffer in a multi-line format. 

For interest this macro is defined as: 

t \84 Woc?b7f*da 
Won-om+Ozkl 

\fful sA\\\\\\V\\80/ 

Wul sA\\\le/\\le/ 

Wul *sA\80A\\\\\\V 
W0zce255 IzchlbS 
Wom+ 

Wul *s/$A\\\le/ 

Wu40 Ij 

WlzkOzchloc+ 

This macro uses UNTIL commands to prevent errors should a substitute fail. 

In the case where you are on the command line, it deletes your buffer and places an 
empty line in it via the APPEND command. It then copies the command line to the 
empty line and splits the line at each\le. Note that it is not tricked by a\\le se¬ 
quence. 

The reverse process appends each line with a Me sequence, joins all lines, then 
copies it to the command line. It leaves the joined line in your text buffer allowing 
you to save it with a write or write append command. 



At this point you should examine the macros defined in the file "/cmds/ed.macros" 
to gain further insight into the writing of new macros. You may examine them by 
reading the file, or by displaying each key’s translation one at a time via the "t ? 
\hh" command and then using the F4 key to show it as a nice multi-line sequence. 
If you do not know the hexadecimal value of a key, then you may enter it’s literal 
value by preceding it with the macro disable key (MINUS key on the keypad). For 


- Start of code in the case 
where you are in the text area. 
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example, you could type either 

t ?\§t 
or 

t 9 <MINUS keyxFl key> 


The possibilities for macros are endless. QNX Software Systems encourages their 
fullest possible use, but warns you that creating them is very much a black art... 
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APPENDIX A - ERROR MESSAGES 

The Full Screen Editor prints any errors it detects on the command line and pauses 
for you to type a carriage return to clear the error. 


out of memory 

The Editor was unable to allocate space to replace an existing line or add a 
new line. 

unknown command 

The editor encountered an unknown major command or subcommand 
character. 


invalid pattern specification 

A pattern was specified which was not acceptable because: 

- Terminating delimiter of pattern missing. 

- Pattern exceeds 128 characters. 

- Pattern starts with a 

- // pattern specified when no pattern was defined. 

buffer has been modified, use qq to quit without saving 

An attempt to leave the editor via the quit command when your text buffer 
has been modified since your last write to a file. 


invalid line number or line range 

A command has detected an invalid line number or range of line numbers. 
This can be caused by: 

- <linel>,<line2> where <linel> is greater than 
<line2>. 

- <line> is greater than the last line in the buffer. 

- <line> is zero on a command other than a,k,m,r or z. 

- Target of a move or kopy falls within the source 
range. 
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x command encountered within an execute file 


An attempt has been made to nest execute commands. 


current file not defined 

An e,r,w or x command was entered without a filename and no current 
filename was defined. You can define it with the f command. 


unable to access file 

The file system was unable to open the requested file. This can be caused 

by: 

- Invalid filename specified. 

- No permissions to open file, (read, write or append) 

- Filename specified can not be found. Check spelling. 


syntax error 

A. recognised command was specified incorrectly Some commands 

which do not take a line range will flag a syntax error if given one (eg: e, 

0 . 


filename too long 

A pathname of more than 64 characters was specified on a e,f,r,w or x 
command. 


unknown option 

An unknown option character was specified in the option command. 


line greater than 512 chars 

On a read from a file, a line greater than 512 characters was encountered. 
The line is broken at 512 characters. Reading will continue when you 
type carriage return. The j and s commands can also cause this error. 
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pattern not found 

The pattern specified in a line search or a substitute command was not 
found anywhere in the buffer. 


disk error 

An error has occurred while trying to read/write a disk file. Make sure that 
the disk is not write protected (if writing). Otherwise, this error may 
signal a defective diskette or a bad block. 


Attempt to write to a file which is not the current file. Use ww 

to force. 

You are trying to write to a named file which is different from the one you 
edited. Perhaps you wanted to type "e file" and missed the V and hit the 
*w* instead. If you are sure, recall the line using the F10 key and insert a 
second ’w’ for a command of "ww file". 
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1. Operating System Limits 

This section describes limits of the QNX operating system at the time of printing. 
Use the TSK command to verify what your version supports. For more informa¬ 
tion call our Technical Support line. 

1.1 File System Limits 


Max 

Max 

Max 

Max 

Max 

Max 

Max 

Max 

Max 

Max 

Max 

Max 

Max 


These are the same for PGAT and ATP versions 


number of extents per file: 
bytes per extent: 
files per directory: 
blocks per disk: 
disk volume size (bytes): 
file size (bytes): 
number open files: 
number QNX drives: 
number mounted drivers: 
number adopted drives: 
drives/nodes in search: 
characters in filename: 
characters in a pathname: 


65,535 

2,147,483,647 

32,767 

2,147,483,647 

1,099,511,627,776 

1,099,511,627,776 

4 to 1000 (configurable). Default ->64. 

8 

8 

16 

8 

16 

256 


1.2 Device Limits 


PC AT ATE 

PHYSICAL TTY’s (console): 1* 1* 

(serial ports): 10 16 

(parallel ports): 2 2 

Additional ADOPTABLE TTY’s: 20 40 


* Unused serial/parallel port device entries can be used to mount up to 7 extra consoles. 

1.3 Other Limits 


Tasks (combined virtual and local): 
Ports: 

Accounting Entries: 

Registered Names (local): 

Extra Segments (configurable): 

Memory: 


PCAT 

ATP 

64 

150 

28 

40 

50 

100 

30 

50 

160 - 

160 

to 200. 

to 800 

640K 

640K Base 
+ up to 15Meg 


Extended 
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NOTE: Only one RAMDISK can be mounted. 
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2. Floppy and Tape Backup for QNX 


Please read this entire document before deciding on 
an archive philosophy. 

All examples using FBACKUP also apply to TBACKUP 


2.1 Introduction 

When saving large amounts of data to floppy diskette the QNX BACKUP com¬ 
mand poses several problems. It is relatively slow and no single file may be 
greater than the size of the floppy. The solution to this is the FBACKUP and 
TBACKUP commands which are very fast and allow files to span media boun¬ 
daries. 

FBACKUP® Archive to floppy diskette or Bernoullie 
removable hard disks. 

TBACKUP® Archive to 1/4 inch tape cartridge using Everex, 

Tecmar and Wangtek QIC60 internal/external tape units. 


The set of floppy diskettes or tapes produced is called an archive and may only be 
manipulated by the FBACKUP or TBACKUP commands. In other words, you 
may not use LS, COPY,... on archive diskettes and tapes. 

There are seven functions provided by the FBACKUP and TBACKUP commands. 


config 

init 

files 

name 

save 

restore 

verify 


® Configure the tape hardware. Used by TBACKUP only. 
9 Initialize a floppy/tape for archiving. 

® List files in an archive. 

• Print the volume name of the archive. 

® Disk to archive save. 

® Archive to disk restore. 

° Disk and archive compare. 


Maintaining an archive system involves several phases, as follows. 

Phase 1 

Before you can use a diskette/tape for archive backup it must be initialized. This is 
done using the the INIT function to the FBACKUP or TBACKUP command. Note 
that only the first diskette/tape of an archive should be initialized. 
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Phase 2 

Files can now be saved on the floppy/tape using the SAVE function. This function 
supports a rich series of options similar to the QNX command called BACKUP. 

Phase 3 

After a SAVE you may wish to run a verify operation on the tape. This is op¬ 
tional. If performed, it should be run on a new tape. 

Phase 4 

In the event of a catastrophe, you may have to restore files saved in the archive 
back to a disk using the RESTORE function. This may be needed in the case of a 
hard disk malfunction, or in the case of a "boo-boo'\ such as accidentally releasing 
a file. 

2.2 Archive Structure 

The first block of each archive diskette/tape contains the name of the archive and 
the sequence number of this diskette/tape. 


volume name I directory I file 1 I file 2 

Diskette/tape 1 floppy only 


volume name I continued data 

Disk©tte/tapa 2 


In the case of FBACKUP the first floppy also contains a fixed length directory 
which is created when the archive is initialized. The data is stored after this direc¬ 
tory. The floppy data portion of the diskettes are formatted without any sector 
interleave. FBACKUP uses multi-sector I/O to maximize the data rate to and from 
the diskettes. 

2.3 Backup Philosophy 


Using a file-by-file system, one backup technique available is called incremental 
backup. In this technique, a backup of all files is performed periodically, and a 
backup of the modified files is done more frequently. For example, a complete 
backup of all files may be performed Monday evening at closing time. Then, on 
Tuesday through Friday, only the modified files are saved into separate directories 
on the archive. In the next week, the process is repeated with a DIFFERENT set of 
archive diskettes. Depending on preferences, there may be four or five archives 
being cycled in this fashion. If a complete restore is needed, restore from the last 
complete backup, then restore from each of the partial backups taken since then. If 
only one file is needed, look in the most recent partial backups first, and if it is not 
found there, restore the file from the most recent complete backup. 
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Some computer centers also like to maintain archival copies of their files. In this 
case, every fourth incremental archive, for example, could be filed away instead of 
being cycled. Of course, it would have to be replaced with a new archive to enter 
the cycle of incremental archives. In this way, a record of all files would be kept 
for each month, approximately. 

Although incremental backups are faster and smaller, they are more complex to 
restore from. You have to determine the day on which the file was last saved. 

This will be Monday and perhaps one or more weekdays. A full backup every day 
eliminates searching for files on the archive, at the expense of using diskettes/tapes 
and time. 

Lastly, when backing up a large database, a single change to a record entails saving 
away the complete file, which may be many megabytes. In this case, an in¬ 
cremental backup may not save any time since die large database files may change 
(if even a little bit) every day. 

2.4 Detailed Command Descriptions 

Each of the five functions provided by the FBACKUP and TBACKUP commands 
will be described separately. Typing 

fbackup ? 
or 

tbackup? 

will give you a usage message should you forget one of the option letters. Note that 
only the first two letters of a FBACKUP/TBACKUP function need be entered. 
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2.4.1 CONFIG - Configure the Tape Hardware 

Syntax: 

tbackup config c =dma__channel I =io_port u=aleli 

where unit is: u=a • Archive Scorpion (internal or external). 

u=e ® Everex/TecmarAVangtek external. 
u=i • Everex/TecmarAVangtek internal. 

Description: 

To use the TBACKUP command you must first configure the TBACKUP com¬ 
mand to your hardware. This is done using the CONFIG function. This will create 
a file called /config/tape.w where n will be replaced by your node number. This 
will be zero in a non-networked system. For example, to configure an external 
tape unit which uses ioport 338 and dma channel 3 you would type. 

tbackup coring c=3 1=338 u=e typical AT setup 

On a PC with a hard disk, dma channel 3 is already in use. You should set your 
tape controller card to use use DMA channel 1. 

tbackup config c=l i=338 u=e typical PC setup 
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2.4.2 INIT - Initalize NEW Archive 

Syntax: 

fbackup [drive] init max-num-files ["v= volume-name ''] [^capacity] 

[-format] [f =format_cmd] 

tbackup init ["\=volume-name"] 


The INit option will reformat the diskette/tape. In the case of a floppy archive 
y°u m ust reserve room for a directory which can contain up to the number 

StowIngSzes ^ MSp ” 8flopPy diske “ e “ d is “ 


Floppy Size 
360K 
720K 
1.2Meg 


Max Number of Files 
2876 (c=360k) 

5756 (c=720k) 

9596 (c=1.2m) 


The size of the archive may be selected to be one of three standards using the od- 
tions provided. The 720K size requires an 80 track disk drive while the 1 2Meg 
size requires a high capacity disk drive on an AT. You may of course create an 
archive with a much smaller number of files in the directory. This will leave more 
room for data on the first diskette. 

TT WlU Suppre , ss the messa ge that this will destroy an existing 
archive. It will also suppress the reformatting of the diskette. The t=format cmd 

forn^^n e iOME^A e ca^dge. 0mman< ^ * f0imat ^ media ' ™ S i$ needed Fo 

m format option^ 6 y ° U d ° n0t need t0 specify the director y size, tape size 

raLFS onSn * e ar - hiVe ? V 0 , 1 T e name - The name will be displayed by the 
,.S option. The name is optional, but is recommended so you can tell one ar- 

an0tI T' Pi SA ,y E “ d RESTORE functions have anTption 

%u ve™p"Zg. W V6nfy 111311116 V ° lumename of the arc hive is what 

Mn U SA VF^y/ln 7 ° n th K firel flopp y /tape before you can use the archive. You 

cm SAVE files any number of times to an existing archive. Until you re-create it 

the new data is simply appended to the end of any existing data. 
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2.4.3 FILES - List Saved Files In the Archive 


Syntax: 

fbackup [drive] files [directory] [options]* 
tbackup files [directory] [options]* 


directory 

pf =[ A ]pattern 
PP=[ A 1 pattern 
^verbose 
+verbose 
4-summary 



Show only files in this directory. 

Show only files whose names match this pattern. 
Show only files whose full path match this pattern. 
Show only the file names. 

Show complete information. 

Show only a summary of the directory. 


The FILES option prints a list of the names of the files that have been saved in the 
archive. In fact, the FILES command is almost identical to the QNX FILES com¬ 
mand. 

The directory option allows you to look at just those files contained within a par¬ 
ticular directory or subdirectory. If you do not specify, the FILES command will 
show files starting at the root directory. 

The pi=pattern option allows you to specify part or all of the name(s) you want to 
see. For example, to see information about the file called "testx", you could 
specify the option as M pf=testx". Only files with a name matching that pattern, in 
this case "test.c", will be listed. To get information about all files whose names end 
with ”x", you could specify "pf=*x". See the QNX FILES command for more 
information on patterns. If you do not specify a pattern, any file name will be 
displayed. You may specify more than one pattern including patterns which do not 
match a file. For example: 

fbackup files pf= A *.o • match all files that do not end in .0 
You may abbreviate pf= to a simple p=. 

The pp ^pattern option operates the same as the pf= option except the entire path¬ 
name is matched against the pattern, not just the trailing filename. For example. 
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fbackup files pp=*/dir/* 


match all files under a directory. 


The +verbose and -verbose options determine how much information is shown for 
each file. If neither is specified, the FILES option will display each file’s name, 
date, time, and size. If the -verbose option is used, only the file’s name is shown. If 
the +verbose option is used, each line of output will show the file’s name, date, 
time, size, group and owner numbers, attributes, permissions, and the location of 
the file in the archive. 

If the +summary option is used, no file names will be listed. Only statistics on the 
number of files and size of the archive will be displayed. 
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2.4.4 SAVE - Save Files to the Archive 

Syntax: 

fbackup [drive] save save_spec ... [options]* 

tbackup save save_spec ... [options]* 

savejspec: disk_dir[ 9 arch_dir] 

x=indexjile[ 9 arch_dir] 
filename [ 9 arch_dir] 


Options: 

disk-dir 

,arch-dir 

+all 

-clear 

+list-only 

+pause 

-verbose 

pf -pattern 

pd-pattern 

pp=pattern 

g-group 

m -member 

d =date 

i-time 

+before 

1 -levels 

t-errjile 


Directory to save files from disk. 

Directory to save files to arch. 

Save all files, modified or not. 

Do not clear the file’s modified bit. 

Show what will be done, but don’t do it. 

Prompt for diskette/tape before starting. 

Do not print filenames while operating. 

Save only files whose names match this pattern. 

Save only directories whose names match this pattern. 
Save only files whose full path match this pattern. 
Save only files belonging to this group. 

Save only files belonging to this member. 

Save only files created/modified since this date. 

Save only files created/modified since this time. 
Change sense of d= and t=. 

Only descend this far in subdirectories. 

Name of files to place errors in. 


Tape only options: 

-hog • Never hog more than 256K of memory. 

+hog • Hog has much memory as possible. 

+tension • Tension the tape before saving. Use if tape 
has been banged, subjected to cold/heat or 
unused for some time. 


Description: 


The SAVE function is the one which does the real work. It copies files from a 
QNX disk to the floppy/tape archive. If you perform a save with the intention of 
repartitioning or reformatting your hard disk please follow the SAVE function with 
the VERIFY function before you release the file(s). Play it safe. 
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You may specify the files to be saved in three ways. You may mix these types on 
the same save command. 

1. A directory name in which case all files under the directory will be saved. You 
may restrict the files saved using the other options. For example, pf= and g=. 

fbackup save 3:/ pf=*.[ch] 
fbackup save /projects/alpha g=12 


2. An index file in which each line of the file contains the pathname of a file to be 
saved. The names files will always be saved regardless of any selection options 
set. 

fbackup save x=indexJRle 


"■3. A simple filename. The file will always be saved regardless of any selection 
options set. 

fbackup save /data/dbase.dat /data/dbase.idx 


In all cases, the full pathname from die root of the file is saved in the archive. The 
node and drive number are not saved. The ,arch-dir option right after the source 
disk directory name (no space), allows you to prepend additional directory infor¬ 
mation to the file name which is saved to the archive. For example, if you simply 
type 

fbackup save /user/george 

all of george’s files will be saved under /user/george in the archive. If, however, 
you type 

fbackup save /user/geor ge,/Wednesday 

then george’s files will be saved under /wednesday/user/george. You can use this 
to prepend a drive and node number as well so that 

fbackup save 3:1,3:1 
fbackup save [4]3:./ 9 [4]3:/ 

will save your files under [4]3:/, not just /. This should be used if your disk sup¬ 
ports more than one QNX hard disk partition or you will NOT be able to differen¬ 
tiate which partition a file came from. 
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The -clear option pertains to the modified bit of a file. This is a bit contained in the 
directory entry of a file on a QNX disk that indicates whether or not the file has 
been modified. Any time the file is written to, the bit is set. Usually the SAVE 
function will clear the bit after saving the file to the archive. Using the -clear op¬ 
tion indicates that the SAVE option is to leave the bit alone. 

The +all option tells SAVE to save all files, even if they have not been modified. If 
this is not specified, only files that have been changed since the last backup will be 
saved. 

The +pause option tells the SAVE option to prompt for a diskette/tape before star¬ 
ting. If it is not specified, the command will start immediately. 

The -verbose option inhibits the command’s display of information messages while 
it is operating. These messages indicate the name of the file currently being saved. 
The program will, however, still print messages about any errors it encounters 
while operating. 

The +!ist-only option can be used to verify that things will happen the way you 
want them to. The file names will be processed, as usual. However, no data will be 
transferred. The file names will be listed on the terminal. 

The pf ^pattern option allows the user to specify which files are to be saved. Only 
files whose names match the specified pattern will be saved to the archive. For 
example, to save only files whose names end with the characters ".c", you could 
specify the option "pf=*.c". You may specify more than one pf= option. You can 
also specify a pattern which excludes files. For example. 

fbackup save 3:/ pf=*.c pf=*.h • Save only C and header files 
fbackup save 3:1 pf= A *.o • Don’t save object files 

For more information, see the QNX BACKUP command. If this option is not 
specified, the file’s name is not considered while it is being saved (unless pp= is 
specified). 

The pd-pattern option allows the user to specify which directories are to be saved. 
It is identical to the pf= option above, except that it operates only on directory 
names. 

The pp ^pattern option allows the user to specify which full pathnames are to be 
saved. It is identical to the pf= option above, except that it operates on the full 
pathname, not just the filename (or directory name in the case of pd=). For exam¬ 
ple. 
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fbackup files pp=*/dir/* 


match all files under a directory* 


The g =group and m -member options refer to the group number and member 

number assigned to each user of a QNX system. When you login with your name, 
your group and member numbers are read from the system password file. 
Thereafter, any files that you create contain your numbers. By specifying these 
options, SAVE will save only files created by a particular user. For example, if 
user george is assigned group number 2, member number 5, you could save only 
george’s files by specifying "g=2 m=5". You can save files created by any member 
of group 2 by specifying just "g=2", or you can save files created by user 5 of any 
group by specifying "m=5" (although this would seem to be of limited usefulness). 
If neither of these options is specified, the group and member numbers are not 
considered when files are being saved. 

QNX updates the date and time of each disk file any time the file is changed. The 
d -date and t =time options allow you to specify which files to save based on the 
last time they were modified. If you specify the date or time, only files changed 
since that time will be saved. For example, to save any files changed or created 
since 8 a.m. on October 28,1985, you would specify 


d=28-10-851=8:00 

The date is specified as yy-mm-dd, and the time is specified as hh:mm:ss, in 
24-hour format. If not specified, the date and time are not considered when files 
are being saved. Specifying a particular date and time is usually used because the 
modified bit cannot be used. This option is therefore typically used with the +all 
option. 

The +before option changes the sense of the d=date and t-time options. Instead of 
saving files changed SINCE the indicated date, it will save files changed BEFORE 
the given date. 

The 1 -levels option allows you to control how far the SAVE option descends into 
subdirectories looking for files. For example, if you specify "1=1", only files in the 
top directory will be saved. If you specify "1=2", only files in the top directory ard 
in the next level of subdirectories will be saved. If not specified, SAVE will de¬ 
scend to all subdirectory levels. 

Here are some general notes about the SAVE option. 

When SAVE locates a file that is to be saved, it determines the complete pathname 
of that file, even though you may not have given the complete path when you 
typed the command. For example, if your current directory is /user/george, and 
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you have a subdirectory called stuff, you may save the files in staff by typing 
fbackup save staff 

However, the files will appear on the archive as /user/george/stuff/filel, 

/user/george/stuff/file2, and so on. If you specify an " 9 arch-dir" on the archive, 
the complete path will be appended to the destination archive directory name. For 
example, if you type 

fbackup save stuff,/foo 

the files will be saved as /foo/user/george/stuff/filel, /foo/user/george/stuff/file2, 
and so on. 
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2.4.5 RESTORE - Restore Files from an Archive 


Syntax: 

fbackup [drive] restore disk-dir[,arch-dir] [options]* 
tbackup restore disk-dir[,arch-dir] [options]* 

Options: 

disk-dir - Restore files to this directory. 
f arch-dir - Restore files from this archive directory. 

+pause - Prompt for diskette before starting. 

-verbose - Do not print files while operating. 

-create - Do not create files or directories on the disk, 

pf -pattern - Restore only files whose names match this pattern, 

pp ^pattern - Restore only files whose full path match this pattern, 

g =group - Restore only files belonging to this group, 

m =member - Restore only files belonging to this member, 

d =date - Restore only files created/modified since this date. 

t-time - Restore only files created/modified since this time. 

+before - Change sense of d= and t=. 

4-list-only - Show what will be done, but don’t do it. 

Description: 

The RESTORE option is the inverse of the SAVE option. With a little luck, you 
will never need to use it. The RESTORE option copies files from the archive to a 
QNX disk. This is presumably used to restore files which have been corrupted or 
accidentally released. You should be sure to correct any problems that caused the 
corrupted file (such as bad disk blocks) before restoring the file. 

The RESTORE option has one mandatory parameter. You must specify the de¬ 
stination directory where the files are to be written. For example, if you want to 
restore all the files on the archive to drive 3, you would type 

fbackup restore 3:1 

You can also restore files from the archive into a subdirectory. For example, typing 
fbackup restore /oldjlles 
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will read files from the archive and write them into the directory /oldjiles. If there 
are subdirectories on the archive, they will be created as subdirectories of 
/oldfiles. 

If an archive directory is specified on the command line, it is presumed to be a 
source directory in the archive. This is the directory in the archive from which 
files are to be read. For example, typing 

fbackup restore /user/fred,/user/george 

will restore all of george’s files from the archive into fred’s directory. Note that the 
path of the archive directory is stripped from the name of the file and that only files 
within this directory will be restored. 

The following examples may clarify things. 

fbackup restore /user/geor ge 

* Restore ALL files from the archive. 

Take the names and save them under /user/george. 

Arch File -> Disk File 
/ user/george/file / user/ george/user/george/file. 

/cmds/Is /user/george/cmds/ls 


fbackup restore /user/george,/user/george 

• Restore only files under /user/george from the archive. 
Strip the /user/george from each archive name. 

Take these names and save them under /user/george. 
Arch File -> Disk File 
/user/george/file /user/george/file. 


fbackup restore /user/fred,/user/george 

• Restore only files under /user/george from the archive. 
Strip the /user/george from each archive name. 

Take these names and save them under /user/fred. 
Arch File -> Disk File 
/ user/ george/file / user/ fred/file. 
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fbackup restore 3:/ 

• Restore ALL files from the archive. 

Take these names and save them under 3:1 
Arch File -> Disk File 

/dir/file 3:/dir/file 


fbackup restore 3:/,4:/ 

• Restore only files under 4:/ from the archive. 

This assumes an archive dir of ,4:/ when SAVE was run. 
Strip the 4:/ from each archive name. 

Take these names and save them under 3:/. 

Arch File -> Disk File 
4:/dir/file 3:/dir/file 


fbackup restore [3]3:/,[2]3:/ 

• Restore only files under [2]3:/ from the archive. 

This assumes an archive dir of ,[2]3:/ when SAVE was run. 
Strip the [2]3:/ from each archive name. 

Take these names and save them under [3]3:/. 

Arch File -> Disk File 
[2]3:/dir/file [3]3:/dir/file 


The -create option prevents the RESTORE option from creating new files or direc¬ 
tories on the disk. If not specified, new directories will be created if they do not 
exist. For example, if george’s files are all saved in the archive, and then george’s 
directory is released, typing 

fbackup restore /user/george,/user/george 

will restore all the files, and RESTORE will create directory /user/george on the 
disk so it can write the files into it. If the -create option is specified and a necessary 
directory cannot be found, the RESTORE option will print an error message for the 
file it was trying to restore and will then proceed to the next file. 
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The remaining options have the same meaning as they do in the SAVE option. 
They apply to files in the archive to be restored, instead of files on the disk to be 
saved. 


+list-on!y 

-pause 

-verbose 

pi-pattern 

pp=pattern 

g -group m-memher 

d -date t-time 

+before 


QNX18 



2.4.6 VERIFY - Verify Data Saved to the Tape/Diskette 

Syntax: 

fbackup [drive] verify disk-dir[,arch-dir] [options]* 
tbackup verify disk-dir[,arch-dir] [options]* 

Description: 

The VERIFY function can be used to verify that data was saved correctly in the 
archive. It should follow the SAVE option before any disk files are modified. 

When this function is specified, the data from the archive IS NOT written to the 
disk files. Instead the disk files are read and compared to the files in the archive. 

This function supports the same options as the RESTORE function. 

fbackup save 3:1 
fbackup verify 3:1 
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2.4.7 NAME - Print Volumn Name of an Archive 


Syntax: 

fbackup [drive] name 

tbackup name 

The NAME function will print the volume name on an diskette or tape. It is useful 
if you forget to label your archive. 

2.5 Examples 

The following is an example of the use of INIT option. 

$ fbackup init 200 ,f v=test-disk" 

$ tbackup init "v=test-tape 5! 



In the following examples, we assume that the user’s hard disk is mounted as drive 
3. We also assume a 1.2meg floppy drive. If this is not the case in your system, 
you must specify the correct parameters. 

Here we describe the commands to be used to implement the incremental backup 
system outlined in section 1.3. 

On Monday, type the command 

$ fbackup init 200 v=week35 +h 
$ fbackup save 3:/,/monday +all ■ 

The first command creates a brand new archive. You may use any volume name 
you like. In this example, the volume is named for the week of the year. 

The second command will save all files from the hard disk to the archive. This is 
the complete backup, which happens each week. 

On Tuesday, type the command 

$ fbackup save 4:/,/tuesday 
On Wednesday, type the command 
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$ fbackup save 4:/, /Wednesday 

On Thursday and Friday, follow a similar scheme. These commands save only the 
files which have been changed that day into a directory with the name of the day. 

By the end of the week, you will have made a complete backup of your files, and 
all of the changes that have been made through the week. 

Using the example above, you could restore all files that changed on Thursday by 
typing 

$ fbackup save 3:/,/thursday 

If your disk is destroyed for any reason, the contents of the disk can be completely 
restored from the archive by issuing in order a command for each day. 

$ fbackup restore 3:/,/monday 
$ fbackup restore 3:/,/tuesday 


2.6 Saving Multiple Disk Partitions Per Archive 

If your hard disk contains more than one QNX partition, say disk 3 and disk 4, and 
you wish to save them both on one archive you SHOULD use the ,arch-dir option. 
This allows you to differentiate there files once they are placed in the archive. For 
example. 

fbackup save 3:1,3: 
fbackup save 4:/,4: 

Or using just one command 

fbackup save 3:1,3: 4:1,4: 

This can of course be extended to include node numbers in a networked system, 
fbackup save [2]3:/,[2]3: 
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QNX Software Systems Ltd. has chosen a rather unique method of storing files on 
disks which provides 

® the flexibility of a true hierarchical file structure 
« the security required in a multi-user environment 
° the fast access using direct seeking in huge data bases 
® the space efficiency of a single 512 byte unit of allocation 

while at the same time minimizing the potential damage which could be caused to 
files when the system crashes (such as during a power failure). 

The QNX File System Administrator views a physical drive as a consecutive array 
of 512 byte BLOCKS (usually disk sectors). The file system assumes a particular 
format of data which is stored in these blocks. Up to 8 drives are supported by the 
File system. These drives may be physical drives, or logical "pieces” of a physical 
drive referred to as partitions. 

1.1 BLOCK 1 - The ROOT Block 

The first block of any disk is the ROOT of the files system and is usually called 
"/”. The ROOT block contains exactly one directory entry (described later) which 
is named and which points to the disk block which contains the directory in¬ 
formation about the files under 7". The rest of the ROOT block is typically not 
used and often contains information required for BOOTing the system. 

Block 0001 

000: 00 00 00 00 00 00 00 00 64 00 00 00 00 00 00 00 <- extent header 

010: 01 00 01 00 31 5A 2F IE 00 00 00 00 00 00 00 00 

020 : 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 

030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 

040: 00 00 00 00 50 07 00 00 00 6F 2F 00 00 04 00 00 

050: 00 05 00 FF FF 00 00 00 00 00 00 00 21 21 35 OF 

060: 62 BA 37 00 00 00 00 00 00 00 00 00 00 00 00 00 


Offset 

010: 

01 

00 

01 00 

<- Father dir extent and index. 

This does not change. 

Offset 

014: 

31 

5A 

2F IE 

<- Date disk was created. 

Offset 

044: 

50 

07 


<- Directory entry which points to the 
root directory just past the bitmap. 


This entry is 48 bytes. 
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3.2 The BITMAP 


Immediately following the ROOT block (block 2) is a file of contiguous blocks 
called the BITMAP. 

2...n Bitmap (n = 2 + NBLKS/512/8) 

This file contains a map of all the blocks on the disk indicating whether or not a 
block is used. Each block is represented by a bit in the bitmap with block 1 being 

the least significant bit of byte 0. If the bit is 1, then the block is in use. The 

DCHECK command with the 4-mark option will also set bad blocks as used so that 
no files will attempt to use them. 

Block 0002 

000: 00 00 00 00 00 00 00 00 4C 09 00 00 04 00 00 00 <- extent header 

010: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF <- file starts on 

020: FF FF FF FF FF FF FF FF FF FB FF FF FF FF FF FF this line. 

First byte at location 010: FF (hex) 

11111111 (binary) 

I I 

| Block 1 of disk 

Block 8 of disk 


The QNX file system uses the bitmap for allocating blocks for new files or files 
which must grow. The bitmap is always kept up to date on the disk (not kept in 
memory) such that in the event of a system failure, the bitmap and directory entries 
will never be inconsistent. 


QNX 24 




The ROOT block points to the first block past the bitmap which will contain the 

root directory, as shown: 


Root Block 


Bitmap Blocks 


Root Directory 

<"— 


3.3 Files 

A QNX file consists of a linked list of EXTENTS which are contiguous arrays of 
blocks. Wherever possible, the QNX file system will try to keep a file contiguous. 

If a file must grow, but the next contiguous disk block is used, then a new "extent" 
is created and linked into the file. 

As a result of the extent philosophy, QNX files may grow to any size (limited only 
by the available space on the disk). Keeping files as contiguous as possible keeps 
disk I/O fairly efficient. 

The extent information is kept within the file itself avoiding the need to seek to a 
known region of the disk to find the next block of a file while still allowing the 
information to be maintained on the disk rather than in memory. This ensures 
consistency of the file system after system crashes. In particular, finding any ex¬ 
tent of a file will allow complete recovery of the file. 
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A typical QNX file has the following structure; 


, Block 1 

Block 2 

Block 3 

I 

V 

, Block 4 

Block 5 

Block 6 

l 

v 

0 , Block 7 

Block 8 

Block 9 


Exteat 1 


Exteat 2 


Exteat 3 


Note; For efficiency, QNX caches the 16 byte extent headers, 

3.4 Extents 

Every QNX file is a linked list of "extents”. An extent is a contiguous array of disk 
blocks. The first 16 bytes of an extent is called an "extent header" which contains 
the following information: 

struct xtnthdr { 
long prevxtnt; 
long next jrtnt; 
long sizextnt; 
long boundxtnt; 

}; 

prev xtnt is zero in the first extent of a file. Similarly 

nextjrtnt is zero in the last extent of a file. 

For example 

Block 0ED1 Status: 00 

000: 00 00 00 00 F8 07 00 00 F0 05 00 00 02 00 00 00 

I prevjctat | aextjctnt | sizejetat | bouadjetat | 

indicates that the previous extent is zero and the next extent is at block 000007f8. 
The size is 000005f0 characters and the number of blocks in the extent is 3 (add 
one to bound_xtnt). 


/* block address of previous extent */ 
/* block address of next extent */ 

/* size of this extent in characters */ 
/* offset of last block in this extent */ 
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After the 16 byte extent header, all remaining bytes are data. 

The fields size_xtnt and bound jrtnt are related. One states die number of charac¬ 
ters in the extent and the other states the number of blocks in the extent. For a 
closed file of a file open for read the following relationship will always be true. 

sizextnt = (bound xtnt + 1) * 512 -16 

If the file is open for write then this relationship may not be true for the last extent 
only. When a file is grown, it is grown by more than one block at a time. As a 
result the bound xtnt keeps track of the number of blocks allocated to the extent 
while sizextnt keeps track of the number of characters written to the extent (user 
data). The amount to grow the file depends on how big the file currently is. When 
the file is closed the extra blocks will be given back to the bitmap and bound xtnt 
shrunk to the proper size. 

When growing a file, if free blocks exist immediately after the last extent, then the 
blocks will be allocated by setting their bits in the bitmap (indivisible operation) 
and then increasing "bound_xtnt" in the file system’s local copy of the extent 
header. Subsequent writes will fill up these blocks. 

When the extent cannot be grown further, the file system will then link in a new 
extent into the file. First a block of memory is allocated from the bitmap. The first 
block of the new extent is initialized to have a size of zero, a next pointer of zero, a 
bound equal to the possible number of blocks in the extent, and a previous pointer 
to the first block of the (now) previous extent. The first block of the previous ex¬ 
tent is then updated with new size/bound/next information. 

The process continues until the file is closed, or no more room exists on the disk. 

When the file is closed, the extent header of the last extent is updated with the 
correct size/bound information and then the bitmap is updated if any blocks al¬ 
located to the file were not actually used. 

Finally, the directory entry is updated (indivisible) with the correct size, first and 
last extent information. 

Notice that at no time will the file ever be inconsistent, although the bitmap may 
indicate more than the necessary number of blocks have been allocated on the disk 
and the last extent and size information in the directory may not be correct. 

Therefore, in the event of system crashes, it is usually possible to read the data in a 
file (which will contain everything flushed to the disk up until the time the system 
went down), but since the last extent information may not be correct, it is wise to 
use the CHKFSYS command to fix the directory entry. If a file can not be cor- 
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rected using CHKFSYS then use the ZAP command to erase the directory entry of 
that file without attempting to give back the blocks to the system. 

In addition, if a file is open for read/write (eg. a database file) and if the file is not 
grown, then all of the extent and directory information will not have been changed 
so it is possible to recover the file to the point of its last disk flush by removing the 
BUSY bit in the file’s directory. 

chattr s=-b file 


The BUSY bit in a file’s directory is set whenever a file is open for write or 
read/write and grows. It is cleared when the file is closed. The reason that this bit 
is maintained in the directory (therefore on the disk) and NOT internal to the file 
system is to ensure that potentially damaged files will be detected after system 
failures. If you do internal writes in a file open for read/write and the file does not 
grow then the BUSY bit will not be set. 

The BUSY bit also provides lockout of files preventing other tasks from opening a 
file which is already open for write or read/write, although this information is also 
maintained internal to the file system. 

3.5 Directories 

QNX directories are QNX files which just happen to contain a known pattern of 
data. 

Each directory file consists of a 4 or 6 byte header followed by one or more direc¬ 
tory entries which are described below. Since directories are really files, they can 
grow to any size. 

The first physical block of a directory contains the standard 
16 byte extent header. This is followed by data as follows. 

struct directory file { 
unsigned parentxtnt; 

unsigned dirindex; <- if top bit set, next word is an 

extension for parent xtnt 
struct dir_entry directory[0...n]; 

}; 
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The 48 byte directory entry is structured as follows: 

struct direntry { 
char fstat; 
long ffirstxtnt; 
long flastxtnt; 
long fnumblks; 
unsigned fnumxtnt; 
unsigned char fowner; 
unsigned char fgroup; 

unsigned fnumcharsfree; /* No. unused chars in last block */ 

long fseconds; 

unsigned char ftype; 

unsigned char fgperms; 

unsigned char fperms; 

unsigned char fattr; 

unsigned fdate[2]; 

char fname[17]; 

}; 


The bits in fstat are defined as follows: 


FILE MODIFIED 

0x10 

USED 

0x40 

FILE BUSY 

0x80 

i in fattr and fperms are defii 

READ 

0x01 

WRITE 

0x02 

APPEND 

0x04 

CREATE 

0x04 

EXECUTE 

0x08 

BLOCK 

0x08 

MODIFY 

0x10 

DIRECTORY 

0x20 


This structure is defined in the file /lib/lfsys.h. 

Note that in the above structure, there are two fields which can hold the file date: 
fdate and fseconds. The field fseconds is new to QNX 2.10. It stores the date and 
time as the number of seconds offset from 0:00:00 GMT, January 1, 1980. The 
field fdate will be de-supported with the next release. In the meantime, if your 
application has opened a directory for read, you should look first at the field 
fseconds. Only if it is zero (0) should you examine the field fdate (in case the file 
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was written under an older version of QNX). If you use the function 
GET DIRJENTRY to obtain the directory entry for a file, both date/time fields will 
be correctly filled in (even though both may not be stored on disk). If you use the 
function SET_DIRJZNTRY to modify a directory entry, both file date fields will be 
recomputed. Changing one field will automatically result in both changing (QNX 
is smart). 
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4. Recovering Files On a Disk 

This technical note will describe several procedures for recovering files, and direc¬ 
tories which have been lost through a software or hardware fault. If the fault ap¬ 
pears to be software and is repeatable, please contact QNX Software Systems Ltd. 

4.1 Utilities Provided 

QNX Software Systems provides the following utilities to aid you. 

chkfsys » Check file system for consistency and 

rebuild the bitmap. Can be used to 
recover zapped blocks (see ZAP command), 
ddump - Dump raw blocks on a disk, 

dinit - Reinitialize a disk. 

relink_file - Create a directory entry and point it 
to the start of a lost file or directory. 
scanJforjSir = Scan the disk, block by block looking for 
a directory. 

scan_for_file - Scan the disk, block by block looking for 
a file. 

spatch - Display and edit raw blocks on a disk. 

All references to a disk refer to a mounted QNX disk or partition which may be a 
subset of the physical disk. All blocks are relative to the start of the mounted 
volume. The examples assume that drive 1 is a floppy, drive 3 the disk which we 
are trying to restore and drive 5 some other mounted disk (ramdisk, floppy etc..). 
Typing any of the commands listed, followed by a question mark will cause it to 
print a very terse usage message. 

4.2 Recovering a Single File on the Disk 

The first step in recovering a file is determining where on the disk it starts. Given 
that, the RELWKJFBLE command can be used to relink to the file. 

You may find a file on the disk using the SCAN_FOR__FILE command if you 
know some of the data within the file. It will simplify your task considerably if the 
data is contained within the first block (512 bytes) of the file. Lets assume we are 
looking for a file which contains the data "#include manifests.h". Enter the com¬ 
mand 

scan_forJHe 3 "#include manifests.h 9 ® 
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The command will read raw blocks from the disk looking for the text indicated. 
Text which spans a block boundary will NOT be matched so keep patterns as short 
as possible. If more than one text string is entered then a match will occur on the 
first block containing ANY of the text strings. 

scanjforjile 3 "match this" "or this" 

If you are lucky it will find the start block of the file and chain through the blocks 

making up the file. You may verify that the correct file was found by dumping the 
file using the DDUMP command or executing the command again specifying a 
starting block and redirecting your output. For example, if a match was found at 
block 6a7 then issue. 

ddump 3 6a7 
or 

scanforfile 3 "#mclude manifests.h" b=6a7 >5:/tmp/data 

If you match the text but it is not the correct file you may continue scanning past 
the matched block using the b= option specifying the next block. 

scan for file 3 "#include manifests.h" b=6a8 

If you match text which is not in the first block, then the command will issue an 
error. Use DDUMP to verify whether you are within the correct file. If you are 
then you will have to use DDUMP to move backward through the file until you 
locate the first block. This is described later on. 

You may relink to the file or simply use the redirected output of the scan com¬ 
mand. Always redirect the output to another disk to prevent overwriting of the file 
you are trying to recover. REMEMBER that to use relink your current directory 
MUST be on the same disk as the file. The directory entry will be created in your 
current directory. 

4.3 Recovering a Directory on the Disk 

The only thing worse than losing a file is losing a directory. Since it is the direc¬ 
tories which contain the information on locating the files beneath it, the loss of a 
directory can imply the loss of all files in that directory. Losing the root of the file 
system means that you have lost all files on your disk! There are several possible 
situations. 
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4.3.1 A Single Entry in a Directory Was Corrupted 

The command SCAN_FOR_DIR is analagous to SCAN_FOR_FILE except it 
matches the names of files in a directory. For example assume a directory struc¬ 
ture as follows. 

user 

1 -- 1 

gord dan bill 


I - 1 - 1 - 1 - 1 

abc def test dir test.c 


I 

filel file2 £ile3 


If the directory ’user 5 is consistent except for the entry for bill then you can locate 
the directory for bill as follows. 


scanjbr_dir 3 abc teste 

The names of files indicated MUST be in the first block of the directory. You may 
specify several names to increase your probability of a match. Redirecting the 
output of this command to capture an image of the directory is possible but is of 
little use. You must relink to the directory to regain access to it. For example if a 
match was made at a68. 


relink_flle billl 3 a68 +directory 

The +directory option is required. If you forget it then you will have to remove 
billl and try again. 

zap billl 

relinkfile billl 3 6a8 +directory 

You may specify a starting block to skip over an incorrect match, 
scan for dir 3 abc test.c b=a69 
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4.3.2 An Entire Directory Was Corrupted 

You must find the start blocks of all files and directories in the corrupted direc¬ 
tory. It is NOT necessary to locate subdirectories. In the example above, if the 
entire directory for bill was lost then you would have to use SCAN_FOR_FTLE 
and SCAN_FOR_DIR to locate 

abc deftest dir iest.e 

on the disk. Record them on a sheet of paper. Now create a new directory under 

user called billl as follows. 

mkdir 3:/user/bil!l 

Position yourself at that directory and issue multiple relink commands. For exam¬ 
ple; 

cd 3:/user/biIll 

relinkfile abc 3 805 

relinkfile def 3 813 

relink file test 3 83a 

relink Jile dir 3 84c +directory 

relink file test.c 3 902 

Zap the corrupted directory out of existence and rename billl. 

chattr a=+w 3:/user/bill 

zap 3:/user/bill 

chattr n=bi!l 3:/user/bi!Il 

You should now run CHKFSYS to ensure the integrity of die file system and to 

correct any errors in the bitmap. 

chkfsys 3 

4.3.3 The Root of the File System Was Corrupted 

If you are unable to access any files on the disk you have probably destroyed some 
of the first blocks on the disk. The structure of the first n+1 blocks are as in detail 
in the technical note called "The QNX File Structure" and are summarized 
below. 
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BLOCK DESCRIPTION 
1 Root descriptor block 
2...n Bitmap (n = 2 + NBLKS/512/8) 

n+1 Root directory (ie: /) 

Remove your hard disk from your search order 

l:/cmds/search 1 - assume drive 1 is a floppy 

and use the DDUMP command to dump the first couple of blocks on your disk. 

ddump 3 1 

If the status returned is other than 00, then a hardware fault has occurred. In the 
case of bad status, try dumping other blocks to determine if the fault is local. If all 
blocks appear bad, your data may still be recoverable if the fault is in the controller 
and not on the physical media (head crash for example). 

The first block of your disk should NOT look like a text file, nor should it consists 
of all zeros, ones etc... The bitmap blocks should consist mostly of FF,’s and 00’s. 
The root directory should contain the names of your root directories (bitmap, cmds, 
lib, config ...). We recommend that you keep a dump of the root directory block’s 
in a safe place. 

ddump 3 1 >$Ipt 

It contains the mapping to ALL sub-directories and files on your disk. 

A good alternative to listing the first blocks of the disk is to DCOPY the first few 
hundred blocks of your hard disk onto a FLOPPY disk which is then kept in a safe 
place. 

Of course the best safeguard is to establish a good backup policy involving daily 
incremental backups and periodic full backups onto floppy disks, streamer tape or 
some other archive media. The BACKUP, FBACKUP or TBACKUP commands 
may be used for this. 

The following is a partial dump of a 10 Meg hard disk partition. 
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ddump 3 1 

Block 0001 Status: 00 


000 : 

00 

00 

00 

00 

00 

00 

00 

00 

64 

00 

00 

00 

00 

00 

00 

00 




.d 





010: 

01 

00 

01 

00 

11 

3B 

A6 

8A 

00 

00 

00 

00 

00 

00 

00 

00 









020 : 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 









030: 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 









040 : 

00 

00 

00 

00 

50 

08 

00 

00 

00 

97 

05 

00 

00 

05 

00 

00 


.E 







050: 

00 

04 

00 

FF 

00 

00 

00 

00 

00 

00 

00 

00 

00 

25 

25 

27 







% 


060: 

49 

81 

93 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

I . 








070 : 

00 

00 

00 

00 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 



n 

n 

n 

n 

n 

n 

080: 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

.n 

n 

n 

n 

n 

n 

n 

n 

090: 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

.n 

n 

.n 

n 

n 

n 

n 

n 

0A0: 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

.n 

n 

n 

n 

n 

n 

n 

n 

0B0 : 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

. n 

n 

, n 

. n 

n 

,n 

n 

n 

0C0 : 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

. n 

n 

,n 

.n 

n 

, n 

. n 

n 

0D0 : 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

.n 

, n 

.n 

,n 

. n 

, n 

n 

. n 

0E0 : 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

DB 

6E 

.n 

, n 

, n 

, n 

, n 

, n 

. n 
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Block 
000 : 

0002 

00 00 

Status: 00 

00 00 00 00 

00 

00 

29 

Oa 

00 

00 

05 

00 

00 

00 


..)- 


010: 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 




020: 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 




030: 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 




040: 

FF 

FF 

FF 

FF 

EF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 




050: 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 




060: 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 




070: 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 




080 : 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 




090 : 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 




0A0: 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 




0B0: 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 




0C0: 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 




0D0: 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 




0E0: 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 




OFO: 

FF 

FF 

31 

72 

8E 

F7 

FF 

8F 

CF 

FD 

F8 

FF 

FF 

FF 

FF 

FF 

. .lr. 



100: 

EF 

F9 

3F 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

CF 




110: 

IF 

FF 

FF 

FF 

DF 

EF 

FF 

FF 

FF 

IF 

F5 

23 

FE 

8F 

FF 

IF 


!!!!!#! 


120: 

FD 

3E 

3E 

26 

IE 

FF 

FB 

3F 

F9 

FF 

3F 

7B 

BE 

FF 

FF 

FF 

.»& . . 



130: 

7F 

FF 

FF 

FF 

Cl 

FF 

FF 

FF 

DF 

F8 

FF 

FF 

FF 

FF 

FF 

FF 
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FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 
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FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

7F 

FC 

9F 

10 

FC 
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FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 
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FF 

FF 

FF 

FF 

FF 

FF 

F9 

03 

30 

06 

FC 

F8 

FF 

FF 

FF 

FF 


!. o!!!! 
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FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

05 

EO 

03 

EO 

FF 

FF 

47 



.G 

190: 
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FF 

FF 

FF 

FF 

FF 

FF 

FF 

F7 

FF 

FF 

FF 

FF 

9F 

FF 
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2F 

FE 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

/..... 



1B0: 

EF 

FF 

FF 

FF 

FF 

FF 

FF 

FB 

FF 

FF 

FF 

7F 

EC 

F8 

FF 

FF 




ICO: 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 
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FF 

FF 

FF 

FF 

FF 
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FF 
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FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 




1E0: 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 




1F0: 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

FF 

7F 

FF 

38 
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Block 0008 Status: 00 

000: 00 00 00 00 A8 06 00 00 F0 01 00 00 00 00 00 00 .. 

010 : 01 00 01 00 40 02 00 00 00 02 00 00 00 06 00 00 -@... ........ 

020: 00 01 00 FF 00 00 00 00 00 00 00 00 00 01 01 31 .1 

030: 35 2E 56 62 69 74 6D 61 70 00 00 00 00 00 00 00 5.Vbitmap....... 

040: 00 00 00 00 50 09 00 00 00 28 28 00 00 10 00 00 ....P-{(. 

050: 00 03 00 FF 00 00 00 00 00 00 00 00 00 21 35 1A .....!5. 

060: 42 3A 9C 63 6D 64 73 00 00 00 00 00 00 00 00 00 B:.cmds. 

070 : 00 00 00 00 50 17 00 00 00 17 00 00 00 06 00 00 -P.... 

080: 00 01 00 FF 00 00 00 00 00 00 00 00 00 21 35 11 .!5. 

090: 42 Bl 51 6C 69 62 00 00 00 00 00 00 00 00 00 00 B.Qlib...... 

0A0: 00 00 00 00 50 IE 00 00 00 IE 00 00 00 06 00 00 .. . .P. 

0B0 : 00 01 00 FF 00 00 00 00 00 00 00 00 00 21 35 3B ..!5; 

0C0: 41 DB 59 62 6C 69 62 00 00 00 00 00 00 00 00 00 A.Yblib. 

0D0 : 00 00 00 00 50 79 02 00 00 79 02 00 00 02 00 00 -Py...y. 

0E0 : 00 01 00 FF 00 00 00 00 00 00 00 00 00 21 35 09 .!5. 

0F0: 41 D5 02 6D 61 74 68 6C 69 62 00 00 00 00 00 00 A..mathlib. 

100 : 00 00 00 00 50 89 02 00 00 89 02 00 00 02 00 00 -P.. 

110 : 00 01 00 FF 00 00 00 00 00 00 00 00 00 21 35 09 .....!5. 

120: 41 ID 35 63 6F 6E 66 69 67 00 00 00 00 00 00 00 A.5config. 

130: 00 00 00 00 50 9F 02 00 00 9F 02 00 00 09 00 00 ....P.. 

140: 00 01 00 FF 00 00 00 00 00 00 00 00 00 21 35 23 ..!5# 

150: 41 EF IB 65 78 70 6C 00 00 00 00 00 00 00 00 00 A..expl. 

160: 00 00 00 00 50 3D 04 00 00 3D 04 00 00 02 00 00 -P=...=-- 

170 : 00 01 00 FF 00 00 00 00 00 00 00 00 00 21 35 09 .!5. 

180: 41 E4 02 65 74 63 00 00 00 00 00 00 00 00 00 00 A..etc. 

190 : 00 00 00 00 50 AC 04 00 00 AC 04 00 00 02 00 00 ....P..... 

1A0: 00 01 00 FF 00 00 00 00 00 00 00 00 00 21 35 09 ..!5. 

1B0: 41 E6 02 71 73 70 65 6C 6C 5F 6C 69 62 00 00 00 A..qspell__lib... 

ICO: 00 00 00 00 50 87 06 00 00 87 06 00 00 02 00 00 -P....... 

IDO: 00 01 00 FF 00 00 00 00 00 00 00 00 00 21 35 09 .!5. 

1E0: 41 EC 02 64 6F 63 73 61 6D 70 6C 65 73 00 00 00 A..docsamples... 

1F0: 00 00 00 00 50 A9 06 00 00 A9 06 00 00 02 00 00 -P. 
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4.3.3a Root Directory Uncorrupted 

If the root directory appears uncorrupted, you may recover by doing a DINIT on 
your disk with the -[-suppress option. 

dinit 3 -[-suppress 

This will write out a new root descriptor block and a new bitmap. The new bitmap 
will indicate all blocks on the disk as free so DO NOT write any files to your disk. 
If there are any files which are critical, back them up NOW. You can rebuild the 
bitmap using the the CHKFSYS command with the -[-rebuild option. This option 
suppresses messages related to a corrupt bitmap. At this point you know your 
bitmap on the disk does not match your file structure. 

dikfsys 3 -[-rebuild 

Answer yes to the prompt to write back the bitmap. Now mn the command again 
without the rebuild option. 

chkfsys 3 

If there are no errors, then your disk has been successfully recovered. If there are 
errors, you can try and fix them, otherwise you will have to DINIT without the 
-[-suppress option and backup the disk from scratch using your backup files. 

4.3.3b Root Directory Destroyed 

If the root directory has been destroyed, DINIT your disk, 
dinit 3 

You will now have to use the SCANJFOR_DIR and SCAN_FORJFILE com¬ 
mands to locate the first block of each directory and file which was at the root of 

the file system. Once located, use the RELINKJF1LE command to relink to the 
directories and files. REMEMBER to use die -[-directory option for directories 

and to position your current directory at the ROOT. 

cd 3:/ 
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Most users do not keep files under the root, only sub-directories. This greatly 
reduces the number of relinks required. After relinking, ran the CHKFSYS com- 
mand twice as above. 

chkfsys 3 +rebuild 

chkfsys 3 


4.4 The Structure Of A File 

This is described in the technical note called "The QNX File Structure". 
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A page is a contiguous set of 512 byte disk blocks. Page caching drivers will do 
both read-ahead and write-behind to maximize performance. Each driver has a 
default cache as follows: 

Driver Pages Pagesize 

disk.ps2 8 8 blocks 

disk.ps2esdi 10 16 blocks 

You may override the cache size using the al -numpages and &2=pagesize 
parameters on the MOUNT command. The maximum number of pages supported 
is 32 and the maximum pagesize is 16 blocks. This cache is intended to speed up 
sequential and record I/O as well as reducing head movement when multiple users 
access the disk at the same time. 

The read-ahead means that requests for a single disk block may result in an entire 
page of disk data being read in a single transaction. When the task next requests a 
block of data, chances are very high that the data will already be in memory. 

The write-behind means that when a task writes a block it may not go immediately 
to disk. The hope is that the task will provide another sequential block and even¬ 
tually fill an entire page which can then be written with one disk transaction. To 
prevent volatile data from staying in the cache, the system ages each page, and 
after one second forces the page to disk. This means you should always pause 1 
second after a write before typing Ctrl-Alt-Shift-Del or hitting the big RED 
switch. As an added precaution, QNX will always write directory and bitmap 
information through the cache onto disk immediately. 

The combination of read-ahead and write-behind optimization means that delays 
due to rotational latency and head repositioning need occur for whole pages, not 
for each block. 

If write-behind scares you, you can turn it on or off when you mount the driver 
using the a3=0|l parameter to MOUNT. You can use the MOUNT command to 
change the default at any time. For example, the following will mount a driver 
with write-behind disabled, enable it and then disable it. 

mount disk 3 /drivers/disk.ps2esdi pa=qnx a3=0 
mount disk 3 d=3 a3=l 
mount disk 3 d=3 a3=0 
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